@buildbase/sdk 0.0.11 → 0.0.13

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import * as react from 'react';
-import react__default, { ReactNode, Component } from 'react';
+import react__default, { ReactNode } from 'react';
 import * as react_jsx_runtime from 'react/jsx-runtime';
 
 interface IDocument {
@@ -355,6 +355,17 @@ interface IAuthCallbacks {
      * @param data - The event data (type varies based on eventType)
      */
     handleEvent?: (eventType: EventType, data: EventData) => void | Promise<void>;
+    /**
+     * Called before switching workspace (e.g. generate token, save state).
+     * Used when user clicks "Switch to" and when restoring from storage on page refresh.
+     * Switch proceeds only when this resolves; reject to abort.
+     */
+    onWorkspaceChange?: (params: OnWorkspaceChangeParams) => Promise<void>;
+}
+interface OnWorkspaceChangeParams {
+    workspace: IWorkspace;
+    user: AuthUser | null;
+    role: string | null;
 }
 
 interface ISettings {
@@ -414,7 +425,71 @@ declare const BetaForm: react__default.FC<BetaFormProps>;
 interface IProps$2 {
     children: React.ReactNode;
 }
+/**
+ * Conditional component that renders children only when user is authenticated.
+ * Returns null if user is not authenticated or authentication status is still loading.
+ *
+ * @param props - Component props
+ * @param props.children - Content to render when authenticated
+ *
+ * @example
+ * ```tsx
+ * function App() {
+ *   return (
+ *     <SaaSOSProvider {...config}>
+ *       <WhenAuthenticated>
+ *         <Dashboard />
+ *       </WhenAuthenticated>
+ *       <WhenUnauthenticated>
+ *         <LoginPage />
+ *       </WhenUnauthenticated>
+ *     </SaaSOSProvider>
+ *   );
+ * }
+ * ```
+ */
 declare const WhenAuthenticated: (props: IProps$2) => react.ReactNode;
+/**
+ * Conditional component that renders children only when user is NOT authenticated.
+ * Returns null if user is authenticated.
+ * Note: Also renders during loading/redirecting states (when not yet authenticated).
+ *
+ * @param props - Component props
+ * @param props.children - Content to render when unauthenticated
+ *
+ * @example
+ * ```tsx
+ * function App() {
+ *   return (
+ *     <SaaSOSProvider {...config}>
+ *       <WhenUnauthenticated>
+ *         <LoginPage />
+ *       </WhenUnauthenticated>
+ *       <WhenAuthenticated>
+ *         <Dashboard />
+ *       </WhenAuthenticated>
+ *     </SaaSOSProvider>
+ *   );
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Handle loading state separately
+ * function App() {
+ *   const { isLoading } = useSaaSAuth();
+ *
+ *   if (isLoading) return <LoadingSpinner />;
+ *
+ *   return (
+ *     <>
+ *       <WhenUnauthenticated><LoginPage /></WhenUnauthenticated>
+ *       <WhenAuthenticated><Dashboard /></WhenAuthenticated>
+ *     </>
+ *   );
+ * }
+ * ```
+ */
 declare const WhenUnauthenticated: (props: IProps$2) => react.ReactNode;
 
 interface IProps$1 {
@@ -422,18 +497,258 @@ interface IProps$1 {
     children: React.ReactNode;
     fallback?: React.ReactNode;
 }
+/**
+ * Conditional component that renders children only when user has one of the specified roles.
+ * Checks the user's global role (not workspace-specific).
+ *
+ * @param props - Component props
+ * @param props.roles - Array of role strings to check against user's role
+ * @param props.children - Content to render when user has matching role
+ * @param props.fallback - Optional content to render when user doesn't have matching role (default: null)
+ *
+ * @example
+ * ```tsx
+ * function AdminPanel() {
+ *   return (
+ *     <WhenRoles roles={['admin', 'super-admin']}>
+ *       <AdminContent />
+ *     </WhenRoles>
+ *   );
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // With fallback
+ * function SettingsPage() {
+ *   return (
+ *     <WhenRoles
+ *       roles={['admin']}
+ *       fallback={<p>You don't have permission to access this page.</p>}
+ *     >
+ *       <AdminSettings />
+ *     </WhenRoles>
+ *   );
+ * }
+ * ```
+ */
 declare const WhenRoles: (props: IProps$1) => react.ReactNode;
+/**
+ * Conditional component that renders children only when user has one of the specified roles
+ * in the current workspace. Checks workspace-specific role, not global role.
+ *
+ * @param props - Component props
+ * @param props.roles - Array of role strings to check against user's workspace role
+ * @param props.children - Content to render when user has matching workspace role
+ * @param props.fallback - Optional content to render when user doesn't have matching role (default: null)
+ *
+ * @example
+ * ```tsx
+ * function WorkspaceSettings() {
+ *   return (
+ *     <WhenWorkspaceRoles roles={['owner', 'admin']}>
+ *       <SettingsContent />
+ *     </WhenWorkspaceRoles>
+ *   );
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Edge case: User not in current workspace
+ * function WorkspaceContent() {
+ *   return (
+ *     <WhenWorkspaceRoles
+ *       roles={['member']}
+ *       fallback={<p>You are not a member of this workspace.</p>}
+ *     >
+ *       <WorkspaceDashboard />
+ *     </WhenWorkspaceRoles>
+ *   );
+ * }
+ * ```
+ */
 declare const WhenWorkspaceRoles: (props: IProps$1) => react.ReactNode;
 
 interface IProps {
     slug: string;
     children: React.ReactNode;
 }
+/**
+ * Conditional component that renders children only when the specified workspace feature is enabled.
+ * Checks feature flags at the workspace level.
+ *
+ * @param props - Component props
+ * @param props.slug - Feature flag slug/key to check
+ * @param props.children - Content to render when feature is enabled
+ *
+ * @example
+ * ```tsx
+ * function PremiumFeature() {
+ *   return (
+ *     <WhenWorkspaceFeatureEnabled slug="premium-analytics">
+ *       <AnalyticsDashboard />
+ *     </WhenWorkspaceFeatureEnabled>
+ *   );
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Multiple features
+ * function FeatureContent() {
+ *   return (
+ *     <>
+ *       <WhenWorkspaceFeatureEnabled slug="feature-a">
+ *         <FeatureA />
+ *       </WhenWorkspaceFeatureEnabled>
+ *       <WhenWorkspaceFeatureEnabled slug="feature-b">
+ *         <FeatureB />
+ *       </WhenWorkspaceFeatureEnabled>
+ *     </>
+ *   );
+ * }
+ * ```
+ */
 declare const WhenWorkspaceFeatureEnabled: (props: IProps) => react.ReactNode;
+/**
+ * Conditional component that renders children only when the specified workspace feature is disabled.
+ * Checks feature flags at the workspace level.
+ *
+ * @param props - Component props
+ * @param props.slug - Feature flag slug/key to check
+ * @param props.children - Content to render when feature is disabled
+ *
+ * @example
+ * ```tsx
+ * function UpgradePrompt() {
+ *   return (
+ *     <WhenWorkspaceFeatureDisabled slug="premium-feature">
+ *       <UpgradeButton />
+ *     </WhenWorkspaceFeatureDisabled>
+ *   );
+ * }
+ * ```
+ */
 declare const WhenWorkspaceFeatureDisabled: (props: IProps) => react.ReactNode;
+/**
+ * Conditional component that renders children only when the specified user feature is enabled.
+ * Checks feature flags at the user level (from UserProvider).
+ *
+ * @param props - Component props
+ * @param props.slug - Feature flag slug/key to check
+ * @param props.children - Content to render when feature is enabled
+ *
+ * @example
+ * ```tsx
+ * function BetaFeature() {
+ *   return (
+ *     <WhenUserFeatureEnabled slug="beta-access">
+ *       <BetaContent />
+ *     </WhenUserFeatureEnabled>
+ *   );
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Edge case: Feature not loaded yet
+ * function FeatureContent() {
+ *   const { isLoading } = useUserFeatures();
+ *
+ *   if (isLoading) return <Loading />;
+ *
+ *   return (
+ *     <WhenUserFeatureEnabled slug="feature-x">
+ *       <FeatureX />
+ *     </WhenUserFeatureEnabled>
+ *   );
+ * }
+ * ```
+ */
 declare const WhenUserFeatureEnabled: (props: IProps) => react.ReactNode;
+/**
+ * Conditional component that renders children only when the specified user feature is disabled.
+ * Checks feature flags at the user level (from UserProvider).
+ *
+ * @param props - Component props
+ * @param props.slug - Feature flag slug/key to check
+ * @param props.children - Content to render when feature is disabled
+ *
+ * @example
+ * ```tsx
+ * function UpgradePrompt() {
+ *   return (
+ *     <WhenUserFeatureDisabled slug="premium-access">
+ *       <UpgradeButton />
+ *     </WhenUserFeatureDisabled>
+ *   );
+ * }
+ * ```
+ */
 declare const WhenUserFeatureDisabled: (props: IProps) => react.ReactNode;
 
+/**
+ * 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>
+ *   );
+ * }
+ * ```
+ */
 declare function useSaaSAuth(): {
     signIn: () => Promise<void>;
     signOut: () => Promise<void>;
@@ -446,9 +761,48 @@ declare function useSaaSAuth(): {
     status: AuthStatus;
 };
 
+/**
+ * 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]);
+ * }
+ * ```
+ */
 declare function useSaaSSettings(): {
     settings: ISettings | null | undefined;
-    getSettings: () => Promise<ISettings | null>;
+    getSettings: (signal?: AbortSignal) => Promise<ISettings | null>;
 };
 
 interface UserContextValue {
@@ -462,7 +816,78 @@ interface UserContextValue {
     refreshFeatures: () => Promise<void>;
 }
 
+/**
+ * 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>
+ *   );
+ * }
+ * ```
+ */
 declare function useUserAttributes(): 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>
+ *   );
+ * }
+ * ```
+ */
 declare function useUserFeatures(): {
     features: Record<string, boolean>;
     isLoading: boolean;
@@ -471,11 +896,111 @@ declare function useUserFeatures(): {
     isFeatureEnabled: (featureId: string) => boolean;
 };
 
-declare function WorkspaceSwitcher(props: {
-    trigger: (isLoading: boolean, currentWorkspace: IWorkspace | null) => ReactNode;
-    onWorkspaceChange: (workspace: IWorkspace) => Promise<void>;
-}): react_jsx_runtime.JSX.Element;
-
+/**
+ * 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 - true when a workspace switch is in progress
+ * - `fetchWorkspaces()`: Function to fetch all workspaces
+ * - `refreshWorkspaces()`: Function to refresh workspaces in background (non-blocking)
+ * - `setCurrentWorkspace(workspace)`: Function to set the current workspace (direct, no callback)
+ * - `switchToWorkspace(workspace)`: Centralized switch - calls onWorkspaceChange first, then sets 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>;
+ * }
+ * ```
+ */
 declare const useSaaSWorkspaces: () => {
     workspaces: IWorkspace[];
     loading: boolean;
@@ -483,16 +1008,19 @@ declare const useSaaSWorkspaces: () => {
     fetchWorkspaces: () => Promise<void>;
     refreshWorkspaces: () => Promise<void>;
     refreshing: boolean;
-    WorkspaceSwitcher: typeof WorkspaceSwitcher;
     currentWorkspace: IWorkspace | null;
-    setCurrentWorkspace: (ws: IWorkspace) => void;
+    setCurrentWorkspace: (ws: IWorkspace, options?: {
+        forceEmit?: boolean;
+    }) => void;
+    switchToWorkspace: (ws: IWorkspace, options?: {
+        forceEmit?: boolean;
+    }) => Promise<void>;
     resetCurrentWorkspace: () => void;
     createWorkspace: (name: string, image: string) => Promise<void>;
     allFeatures: IWorkspaceFeature[];
     getFeatures: () => Promise<IWorkspaceFeature[] | null>;
     updateFeature: (workspaceId: string, key: string, value: boolean) => Promise<IWorkspace>;
     getWorkspace: (workspaceId: string) => Promise<IWorkspace>;
-    switching: boolean;
     updateWorkspace: (ws: IWorkspace, _data: Partial<IWorkspace>) => Promise<void>;
     getUsers: (workspaceId: string) => Promise<IWorkspaceUser[]>;
     addUser: (workspaceId: string, email: string, role: string) => Promise<{
@@ -515,12 +1043,49 @@ declare const useSaaSWorkspaces: () => {
     deleteWorkspace: (workspaceId: string) => Promise<{
         success: boolean;
     }>;
+    switching: boolean;
 };
 
+declare function WorkspaceSwitcher(props: {
+    trigger: (isLoading: boolean, currentWorkspace: IWorkspace | null) => ReactNode;
+}): react_jsx_runtime.JSX.Element;
+
 /**
- * Hook to get and manage the current subscription for a workspace
- * @param workspaceId - The workspace ID to get subscription for
- * @returns Subscription data and loading/error states
+ * Hook to get and manage the current subscription for a workspace.
+ * Automatically fetches subscription when workspaceId changes.
+ *
+ * @param workspaceId - The workspace ID to get subscription for. Can be null/undefined to disable fetching.
+ * @returns An object containing:
+ * - `subscription`: Current subscription data (null if no subscription or not loaded)
+ * - `loading`: Boolean indicating if subscription is being fetched
+ * - `error`: Error message string (null if no error)
+ * - `refetch()`: Function to manually refetch the subscription
+ *
+ * @example
+ * ```tsx
+ * function SubscriptionStatus() {
+ *   const { currentWorkspace } = useSaaSWorkspaces();
+ *   const { subscription, loading, error } = useSubscription(currentWorkspace?._id);
+ *
+ *   if (loading) return <Loading />;
+ *   if (error) return <Error message={error} />;
+ *   if (!subscription) return <p>No active subscription</p>;
+ *
+ *   return <p>Plan: {subscription.plan.name}</p>;
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Edge case: Workspace ID changes
+ * function SubscriptionComponent({ workspaceId }) {
+ *   const { subscription, refetch } = useSubscription(workspaceId);
+ *
+ *   // Subscription automatically refetches when workspaceId changes
+ *   // Use refetch() to manually refresh after mutations
+ *   return <SubscriptionDetails subscription={subscription} />;
+ * }
+ * ```
  */
 declare const useSubscription: (workspaceId: string | null | undefined) => {
     subscription: ISubscriptionResponse | null;
@@ -529,12 +1094,50 @@ declare const useSubscription: (workspaceId: string | null | undefined) => {
     refetch: () => Promise<void>;
 };
 /**
- * Hook to get the plan group for a workspace
+ * Hook to get the plan group for a workspace.
  * Returns the plan group containing the current plan if subscription exists,
- * otherwise returns the latest published group
- * @param workspaceId - The workspace ID to get plan group for
- * @param groupVersionId - Optional: specific group version ID to fetch
- * @returns Plan group data and loading/error states
+ * otherwise returns the latest published group.
+ * Automatically fetches when workspaceId or groupVersionId changes.
+ *
+ * @param workspaceId - The workspace ID to get plan group for. Can be null/undefined to disable fetching.
+ * @param groupVersionId - Optional: specific group version ID to fetch (for viewing historical versions)
+ * @returns An object containing:
+ * - `planGroup`: Plan group data (null if not loaded)
+ * - `loading`: Boolean indicating if plan group is being fetched
+ * - `error`: Error message string (null if no error)
+ * - `refetch()`: Function to manually refetch the plan group
+ *
+ * @example
+ * ```tsx
+ * function PlanGroupDisplay() {
+ *   const { currentWorkspace } = useSaaSWorkspaces();
+ *   const { planGroup, loading } = usePlanGroup(currentWorkspace?._id);
+ *
+ *   if (loading) return <Loading />;
+ *   if (!planGroup) return <p>No plan group available</p>;
+ *
+ *   return (
+ *     <div>
+ *       <h3>{planGroup.name}</h3>
+ *       {planGroup.plans.map(plan => (
+ *         <PlanCard key={plan._id} plan={plan} />
+ *       ))}
+ *     </div>
+ *   );
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Fetch specific version for comparison
+ * function PlanVersionComparison() {
+ *   const { currentWorkspace } = useSaaSWorkspaces();
+ *   const current = usePlanGroup(currentWorkspace?._id);
+ *   const previous = usePlanGroup(currentWorkspace?._id, 'previous-version-id');
+ *
+ *   return <ComparePlans current={current.planGroup} previous={previous.planGroup} />;
+ * }
+ * ```
  */
 declare const usePlanGroup: (workspaceId: string | null | undefined, groupVersionId?: string | null) => {
     planGroup: IPlanGroupResponse | null;
@@ -543,9 +1146,36 @@ declare const usePlanGroup: (workspaceId: string | null | undefined, groupVersio
     refetch: () => Promise<void>;
 };
 /**
- * Hook to get all available versions of a plan group for a workspace
- * @param workspaceId - The workspace ID to get plan group versions for
- * @returns Plan group versions data and loading/error states
+ * Hook to get all available versions of a plan group for a workspace.
+ * Shows current version and available newer versions for upgrade paths.
+ * Automatically fetches when workspaceId changes.
+ *
+ * @param workspaceId - The workspace ID to get plan group versions for. Can be null/undefined to disable fetching.
+ * @returns An object containing:
+ * - `versions`: Plan group versions response with currentVersion and availableVersions
+ * - `loading`: Boolean indicating if versions are being fetched
+ * - `error`: Error message string (null if no error)
+ * - `refetch()`: Function to manually refetch the versions
+ *
+ * @example
+ * ```tsx
+ * function UpgradeOptions() {
+ *   const { currentWorkspace } = useSaaSWorkspaces();
+ *   const { versions, loading } = usePlanGroupVersions(currentWorkspace?._id);
+ *
+ *   if (loading) return <Loading />;
+ *
+ *   return (
+ *     <div>
+ *       <p>Current: {versions?.currentVersion.name}</p>
+ *       <h4>Available Upgrades:</h4>
+ *       {versions?.availableVersions.map(version => (
+ *         <UpgradeCard key={version._id} version={version} />
+ *       ))}
+ *     </div>
+ *   );
+ * }
+ * ```
  */
 declare const usePlanGroupVersions: (workspaceId: string | null | undefined) => {
     versions: IPlanGroupVersionsResponse | null;
@@ -554,9 +1184,62 @@ declare const usePlanGroupVersions: (workspaceId: string | null | undefined) =>
     refetch: () => Promise<void>;
 };
 /**
- * Hook to create checkout session for new subscription
- * @param workspaceId - The workspace ID to create checkout session for
- * @returns Create checkout function and loading/error states
+ * Hook to create a checkout session for a new subscription.
+ * Returns a function to initiate the checkout process.
+ *
+ * @param workspaceId - The workspace ID to create checkout session for. Can be null/undefined.
+ * @returns An object containing:
+ * - `createCheckoutSession(request)`: Function to create checkout session (throws if workspaceId is null)
+ * - `loading`: Boolean indicating if checkout session is being created
+ * - `error`: Error message string (null if no error)
+ *
+ * @example
+ * ```tsx
+ * function SubscribeButton({ planVersionId }) {
+ *   const { currentWorkspace } = useSaaSWorkspaces();
+ *   const { createCheckoutSession, loading } = useCreateCheckoutSession(currentWorkspace?._id);
+ *
+ *   const handleSubscribe = async () => {
+ *     try {
+ *       const result = await createCheckoutSession({
+ *         planVersionId,
+ *         successUrl: window.location.href,
+ *         cancelUrl: window.location.href,
+ *       });
+ *       // Redirect to checkout
+ *       window.location.href = result.checkoutUrl;
+ *     } catch (error) {
+ *       console.error('Failed to create checkout:', error);
+ *     }
+ *   };
+ *
+ *   return (
+ *     <button onClick={handleSubscribe} disabled={loading}>
+ *       {loading ? 'Loading...' : 'Subscribe'}
+ *     </button>
+ *   );
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Edge case: Workspace ID not available
+ * function SubscribeButton() {
+ *   const { currentWorkspace } = useSaaSWorkspaces();
+ *   const { createCheckoutSession } = useCreateCheckoutSession(currentWorkspace?._id);
+ *
+ *   const handleSubscribe = async () => {
+ *     try {
+ *       await createCheckoutSession({ planVersionId: 'plan-123' });
+ *     } catch (error) {
+ *       // Error: "Workspace ID is required"
+ *       alert('Please select a workspace first');
+ *     }
+ *   };
+ *
+ *   return <button onClick={handleSubscribe}>Subscribe</button>;
+ * }
+ * ```
  */
 declare const useCreateCheckoutSession: (workspaceId: string | null | undefined) => {
     createCheckoutSession: (request: ICheckoutSessionRequest) => Promise<ICheckoutSessionResponse>;
@@ -564,10 +1247,71 @@ declare const useCreateCheckoutSession: (workspaceId: string | null | undefined)
     error: string | null;
 };
 /**
- * Hook to update subscription (upgrade/downgrade)
- * Returns checkout session if payment is required, otherwise returns subscription update response
- * @param workspaceId - The workspace ID to update subscription for
- * @returns Update function and loading/error states
+ * Hook to update subscription (upgrade/downgrade).
+ * Returns checkout session if payment is required, otherwise returns subscription update response.
+ *
+ * @param workspaceId - The workspace ID to update subscription for. Can be null/undefined.
+ * @returns An object containing:
+ * - `updateSubscription(planVersionId, options?)`: Function to update subscription (throws if workspaceId is null)
+ * - `loading`: Boolean indicating if subscription is being updated
+ * - `error`: Error message string (null if no error)
+ *
+ * @example
+ * ```tsx
+ * function UpgradeButton({ planVersionId }) {
+ *   const { currentWorkspace } = useSaaSWorkspaces();
+ *   const { updateSubscription, loading } = useUpdateSubscription(currentWorkspace?._id);
+ *
+ *   const handleUpgrade = async () => {
+ *     try {
+ *       const result = await updateSubscription(planVersionId, {
+ *         billingInterval: 'monthly',
+ *         successUrl: window.location.href,
+ *         cancelUrl: window.location.href,
+ *       });
+ *
+ *       // Check if payment is required
+ *       if ('checkoutUrl' in result) {
+ *         window.location.href = result.checkoutUrl;
+ *       } else {
+ *         // Subscription updated without payment
+ *         alert('Subscription updated successfully!');
+ *       }
+ *     } catch (error) {
+ *       console.error('Failed to update subscription:', error);
+ *     }
+ *   };
+ *
+ *   return (
+ *     <button onClick={handleUpgrade} disabled={loading}>
+ *       {loading ? 'Upgrading...' : 'Upgrade'}
+ *     </button>
+ *   );
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Handle both checkout and direct update responses
+ * function SubscriptionUpdater({ planVersionId }) {
+ *   const { updateSubscription } = useUpdateSubscription(workspaceId);
+ *
+ *   const handleUpdate = async () => {
+ *     const result = await updateSubscription(planVersionId);
+ *
+ *     // Type guard to check response type
+ *     if ('checkoutUrl' in result) {
+ *       // Redirect to payment
+ *       window.location.href = result.checkoutUrl;
+ *     } else {
+ *       // Direct update successful
+ *       console.log('Updated subscription:', result.subscription);
+ *     }
+ *   };
+ *
+ *   return <button onClick={handleUpdate}>Update</button>;
+ * }
+ * ```
  */
 declare const useUpdateSubscription: (workspaceId: string | null | undefined) => {
     updateSubscription: (planVersionId: string, options?: {
@@ -579,11 +1323,43 @@ declare const useUpdateSubscription: (workspaceId: string | null | undefined) =>
     error: string | null;
 };
 /**
- * Combined hook that provides both subscription and plan group data
- * Useful for subscription management pages
- * @param workspaceId - The workspace ID
+ * Combined hook that provides both subscription and plan group data.
+ * Useful for subscription management pages that need both pieces of data.
+ * Combines useSubscription, usePlanGroup, and useUpdateSubscription.
+ *
+ * @param workspaceId - The workspace ID. Can be null/undefined to disable fetching.
  * @param groupVersionId - Optional: specific group version ID to fetch
- * @returns Combined subscription and plan group data with loading/error states
+ * @returns An object containing:
+ * - `subscription`: Current subscription data (from useSubscription)
+ * - `planGroup`: Plan group data (from usePlanGroup)
+ * - `loading`: Boolean indicating if any operation is in progress
+ * - `error`: Error message string (null if no error)
+ * - `updateSubscription(planVersionId, options?)`: Function to update subscription
+ * - `refetch()`: Function to refetch both subscription and plan group
+ *
+ * @example
+ * ```tsx
+ * function SubscriptionManagementPage() {
+ *   const { currentWorkspace } = useSaaSWorkspaces();
+ *   const {
+ *     subscription,
+ *     planGroup,
+ *     loading,
+ *     updateSubscription,
+ *     refetch,
+ *   } = useSubscriptionManagement(currentWorkspace?._id);
+ *
+ *   if (loading) return <Loading />;
+ *
+ *   return (
+ *     <div>
+ *       <CurrentPlan subscription={subscription} />
+ *       <AvailablePlans planGroup={planGroup} onSelect={updateSubscription} />
+ *       <button onClick={refetch}>Refresh</button>
+ *     </div>
+ *   );
+ * }
+ * ```
  */
 declare const useSubscriptionManagement: (workspaceId: string | null | undefined, groupVersionId?: string | null) => {
     subscription: ISubscriptionResponse | null;
@@ -598,11 +1374,64 @@ declare const useSubscriptionManagement: (workspaceId: string | null | undefined
     refetch: () => Promise<void>;
 };
 /**
- * Hook to list invoices for a workspace subscription
- * @param workspaceId - The workspace ID to get invoices for
+ * Hook to list invoices for a workspace subscription with pagination support.
+ * Automatically fetches when workspaceId, limit, or startingAfter changes.
+ *
+ * @param workspaceId - The workspace ID to get invoices for. Can be null/undefined to disable fetching.
  * @param limit - Number of invoices to return (default: 10)
  * @param startingAfter - Invoice ID to start after (for pagination)
- * @returns Invoice list data and loading/error states
+ * @returns An object containing:
+ * - `invoices`: Array of invoice objects
+ * - `hasMore`: Boolean indicating if there are more invoices to load
+ * - `loading`: Boolean indicating if invoices are being fetched
+ * - `error`: Error message string (null if no error)
+ * - `refetch()`: Function to manually refetch invoices
+ *
+ * @example
+ * ```tsx
+ * function InvoiceList() {
+ *   const { currentWorkspace } = useSaaSWorkspaces();
+ *   const { invoices, hasMore, loading, refetch } = useInvoices(currentWorkspace?._id, 10);
+ *
+ *   if (loading) return <Loading />;
+ *
+ *   return (
+ *     <div>
+ *       {invoices.map(invoice => (
+ *         <InvoiceCard key={invoice._id} invoice={invoice} />
+ *       ))}
+ *       {hasMore && <button onClick={() => refetch()}>Load More</button>}
+ *     </div>
+ *   );
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Pagination example
+ * function PaginatedInvoices() {
+ *   const [lastInvoiceId, setLastInvoiceId] = useState<string | undefined>();
+ *   const { currentWorkspace } = useSaaSWorkspaces();
+ *   const { invoices, hasMore, refetch } = useInvoices(
+ *     currentWorkspace?._id,
+ *     10,
+ *     lastInvoiceId
+ *   );
+ *
+ *   const loadMore = () => {
+ *     if (invoices.length > 0) {
+ *       setLastInvoiceId(invoices[invoices.length - 1]._id);
+ *     }
+ *   };
+ *
+ *   return (
+ *     <div>
+ *       {invoices.map(invoice => <InvoiceCard key={invoice._id} invoice={invoice} />)}
+ *       {hasMore && <button onClick={loadMore}>Load More</button>}
+ *     </div>
+ *   );
+ * }
+ * ```
  */
 declare const useInvoices: (workspaceId: string | null | undefined, limit?: number, startingAfter?: string) => {
     invoices: IInvoice[];
@@ -612,10 +1441,36 @@ declare const useInvoices: (workspaceId: string | null | undefined, limit?: numb
     refetch: () => Promise<void>;
 };
 /**
- * Hook to get a single invoice by ID
- * @param workspaceId - The workspace ID
- * @param invoiceId - The invoice ID to fetch
- * @returns Invoice data and loading/error states
+ * Hook to get a single invoice by ID.
+ * Automatically fetches when workspaceId or invoiceId changes.
+ *
+ * @param workspaceId - The workspace ID. Can be null/undefined to disable fetching.
+ * @param invoiceId - The invoice ID to fetch. Can be null/undefined to disable fetching.
+ * @returns An object containing:
+ * - `invoice`: Invoice data object (null if not loaded)
+ * - `loading`: Boolean indicating if invoice is being fetched
+ * - `error`: Error message string (null if no error)
+ * - `refetch()`: Function to manually refetch the invoice
+ *
+ * @example
+ * ```tsx
+ * function InvoiceDetails({ invoiceId }) {
+ *   const { currentWorkspace } = useSaaSWorkspaces();
+ *   const { invoice, loading, error } = useInvoice(currentWorkspace?._id, invoiceId);
+ *
+ *   if (loading) return <Loading />;
+ *   if (error) return <Error message={error} />;
+ *   if (!invoice) return <p>Invoice not found</p>;
+ *
+ *   return (
+ *     <div>
+ *       <h2>Invoice #{invoice.invoiceNumber}</h2>
+ *       <p>Amount: ${invoice.amount}</p>
+ *       <p>Status: {invoice.status}</p>
+ *     </div>
+ *   );
+ * }
+ * ```
  */
 declare const useInvoice: (workspaceId: string | null | undefined, invoiceId: string | null | undefined) => {
     invoice: IInvoice | null;
@@ -703,98 +1558,5 @@ declare class EventEmitter {
 }
 declare const eventEmitter: EventEmitter;
 
-interface ErrorBoundaryProps {
-    children: ReactNode;
-    /**
-     * Fallback UI to render when an error occurs
-     */
-    fallback?: ReactNode | ((error: Error, resetError: () => void) => ReactNode);
-    /**
-     * Called when an error is caught
-     */
-    onError?: (error: Error, errorInfo: react__default.ErrorInfo) => void;
-    /**
-     * Whether to reset error state when children change
-     * @default true
-     */
-    resetOnPropsChange?: boolean;
-}
-interface ErrorBoundaryState {
-    hasError: boolean;
-    error: Error | null;
-}
-/**
- * Error Boundary component for catching React component errors
- * Wraps SDK components to prevent crashes from propagating
- */
-declare class SDKErrorBoundary extends Component<ErrorBoundaryProps, ErrorBoundaryState> {
-    constructor(props: ErrorBoundaryProps);
-    static getDerivedStateFromError(error: Error): ErrorBoundaryState;
-    componentDidCatch(error: Error, errorInfo: react__default.ErrorInfo): void;
-    componentDidUpdate(prevProps: ErrorBoundaryProps): void;
-    resetError: () => void;
-    render(): ReactNode;
-}
-
-/**
- * Centralized Error Handler for SDK
- * Provides consistent error handling, logging, and user-facing error management
- */
-interface SDKErrorContext {
-    component?: string;
-    action?: string;
-    metadata?: Record<string, unknown>;
-}
-declare class SDKError extends Error {
-    readonly code?: string | undefined;
-    readonly context?: SDKErrorContext | undefined;
-    readonly originalError?: Error | undefined;
-    constructor(message: string, code?: string | undefined, context?: SDKErrorContext | undefined, originalError?: Error | undefined);
-}
-interface ErrorHandlerConfig {
-    /**
-     * Custom error callback for handling errors
-     * @param error - The error that occurred
-     * @param context - Additional context about where the error occurred
-     */
-    onError?: (error: Error, context: SDKErrorContext) => void;
-    /**
-     * Whether to log errors to console in development
-     * @default true
-     */
-    enableConsoleLogging?: boolean;
-    /**
-     * Whether to show user-facing error notifications
-     * @default false
-     */
-    showUserNotifications?: boolean;
-}
-declare class ErrorHandler {
-    private config;
-    /**
-     * Configure the error handler
-     */
-    configure(config: Partial<ErrorHandlerConfig>): void;
-    /**
-     * Handle an error with context
-     */
-    handleError(error: Error | unknown, context?: SDKErrorContext): void;
-    /**
-     * Notify user of error (placeholder for notification system)
-     */
-    private notifyUser;
-    /**
-     * Create a safe error handler wrapper for async functions
-     */
-    wrapAsync<T extends (...args: any[]) => Promise<any>>(fn: T, context: SDKErrorContext): T;
-    /**
-     * Create a safe error handler wrapper for sync functions
-     */
-    wrapSync<T extends (...args: any[]) => any>(fn: T, context: SDKErrorContext): T;
-}
-declare const errorHandler: ErrorHandler;
-declare function handleError(error: Error | unknown, context?: SDKErrorContext): void;
-declare function createSDKError(message: string, code?: string, context?: SDKErrorContext, originalError?: Error): SDKError;
-
-export { ApiVersion, AuthStatus, BetaForm, SDKErrorBoundary as ErrorBoundary, SDKError, SDKErrorBoundary, SaaSOSProvider, WhenAuthenticated, WhenRoles, WhenUnauthenticated, WhenUserFeatureDisabled, WhenUserFeatureEnabled, WhenWorkspaceFeatureDisabled, WhenWorkspaceFeatureEnabled, WhenWorkspaceRoles, WorkspaceSwitcher, createSDKError, errorHandler, eventEmitter, handleError, useCreateCheckoutSession, useInvoice, useInvoices, usePlanGroup, usePlanGroupVersions, useSaaSAuth, useSaaSSettings, useSaaSWorkspaces, useSubscription, useSubscriptionManagement, useUpdateSubscription, useUserAttributes, useUserFeatures };
-export type { BillingInterval, ErrorHandlerConfig, EventData, EventType, IBasePricing, ICheckoutSessionRequest, ICheckoutSessionResponse, IEventCallbacks, IInvoice, IInvoiceListResponse, IInvoiceResponse, IPlan, IPlanGroup, IPlanGroupLatestVersion, IPlanGroupResponse, IPlanGroupVersion, IPlanGroupVersionWithPlans, IPlanGroupVersionsResponse, IPlanVersion, IPlanVersionWithPlan, IQuotaValue, ISubscription, ISubscriptionItem, ISubscriptionResponse, ISubscriptionUpdateRequest, ISubscriptionUpdateResponse, InvoiceStatus, SDKErrorContext, UserCreatedEventData, UserUpdatedEventData, WorkspaceChangedEventData, WorkspaceCreatedEventData, WorkspaceDeletedEventData, WorkspaceUpdatedEventData, WorkspaceUserAddedEventData, WorkspaceUserRemovedEventData, WorkspaceUserRoleChangedEventData };
+export { ApiVersion, AuthStatus, BetaForm, SaaSOSProvider, WhenAuthenticated, WhenRoles, WhenUnauthenticated, WhenUserFeatureDisabled, WhenUserFeatureEnabled, WhenWorkspaceFeatureDisabled, WhenWorkspaceFeatureEnabled, WhenWorkspaceRoles, WorkspaceSwitcher, eventEmitter, useCreateCheckoutSession, useInvoice, useInvoices, usePlanGroup, usePlanGroupVersions, useSaaSAuth, useSaaSSettings, useSaaSWorkspaces, useSubscription, useSubscriptionManagement, useUpdateSubscription, useUserAttributes, useUserFeatures };
+export type { BillingInterval, EventData, EventType, IBasePricing, ICheckoutSessionRequest, ICheckoutSessionResponse, IEventCallbacks, IInvoice, IInvoiceListResponse, IInvoiceResponse, IPlan, IPlanGroup, IPlanGroupLatestVersion, IPlanGroupResponse, IPlanGroupVersion, IPlanGroupVersionWithPlans, IPlanGroupVersionsResponse, IPlanVersion, IPlanVersionWithPlan, IQuotaValue, ISubscription, ISubscriptionItem, ISubscriptionResponse, ISubscriptionUpdateRequest, ISubscriptionUpdateResponse, InvoiceStatus, OnWorkspaceChangeParams, UserCreatedEventData, UserUpdatedEventData, WorkspaceChangedEventData, WorkspaceCreatedEventData, WorkspaceDeletedEventData, WorkspaceUpdatedEventData, WorkspaceUserAddedEventData, WorkspaceUserRemovedEventData, WorkspaceUserRoleChangedEventData };