@buildbase/sdk 0.0.11 → 0.0.12

package/dist/index.d.ts

@@ -414,7 +414,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 +486,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 +750,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 +805,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;
@@ -476,6 +890,111 @@ declare function WorkspaceSwitcher(props: {
     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 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>;
+ * }
+ * ```
+ */
 declare const useSaaSWorkspaces: () => {
     workspaces: IWorkspace[];
     loading: boolean;
@@ -518,9 +1037,41 @@ declare const useSaaSWorkspaces: () => {
 };
 
 /**
- * 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 +1080,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 +1132,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 +1170,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 +1233,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 +1309,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 +1360,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 +1427,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;
@@ -724,8 +1565,55 @@ interface ErrorBoundaryState {
     error: Error | null;
 }
 /**
- * Error Boundary component for catching React component errors
- * Wraps SDK components to prevent crashes from propagating
+ * Error Boundary component for catching React component errors.
+ * Wraps SDK components to prevent crashes from propagating to the entire app.
+ * Automatically logs errors using the SDK error handler.
+ *
+ * @example
+ * ```tsx
+ * function App() {
+ *   return (
+ *     <SDKErrorBoundary
+ *       fallback={(error, reset) => (
+ *         <div>
+ *           <p>Error: {error.message}</p>
+ *           <button onClick={reset}>Try Again</button>
+ *         </div>
+ *       )}
+ *       onError={(error, errorInfo) => {
+ *         // Custom error reporting
+ *         reportError(error, errorInfo);
+ *       }}
+ *     >
+ *       <YourApp />
+ *     </SDKErrorBoundary>
+ *   );
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Simple usage with default fallback
+ * function App() {
+ *   return (
+ *     <SDKErrorBoundary>
+ *       <YourApp />
+ *     </SDKErrorBoundary>
+ *   );
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Disable auto-reset on props change
+ * function App() {
+ *   return (
+ *     <SDKErrorBoundary resetOnPropsChange={false}>
+ *       <YourApp />
+ *     </SDKErrorBoundary>
+ *   );
+ * }
+ * ```
  */
 declare class SDKErrorBoundary extends Component<ErrorBoundaryProps, ErrorBoundaryState> {
     constructor(props: ErrorBoundaryProps);
@@ -793,7 +1681,47 @@ declare class ErrorHandler {
     wrapSync<T extends (...args: any[]) => any>(fn: T, context: SDKErrorContext): T;
 }
 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' },
+ *   });
+ * }
+ * ```
+ */
 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
+ * );
+ * ```
+ */
 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 };