@buildbase/sdk 0.0.12 → 0.0.14

package/README.md

@@ -95,6 +95,11 @@ export default function SaaSProvider(props: { children: React.ReactNode }) {
             // Handle SDK events (user created, workspace changed, etc.)
             console.log('SDK Event:', eventType, data);
           },
+          onWorkspaceChange: async ({ workspace, user, role }) => {
+            // Called before switching workspace (e.g. generate token). Used on "Switch to" and page refresh/restore.
+            // Switch proceeds only when this resolves; reject to abort.
+            console.log('Switching to workspace:', workspace.name, 'as', role);
+          },
         },
       }}
     >
@@ -124,7 +129,7 @@ export default App;
 
 ### 4. Workspace Management
 
-The WorkspaceSwitcher component uses a render prop pattern, giving you full control over the UI:
+The WorkspaceSwitcher component uses a render prop pattern, giving you full control over the UI. Configure `onWorkspaceChange` in `auth.callbacks` (SaaSOSProvider) to handle workspace switches—used when clicking "Switch to" and when restoring from storage on page refresh. The callback receives `{ workspace, user, role }` so you don't need to look up the user's role:
 
 ```tsx
 import React from 'react';
@@ -160,10 +165,6 @@ function WorkspaceExample() {
           </div>
         );
       }}
-      onWorkspaceChange={async workspace => {
-        // Handle workspace change
-        console.log('Workspace changed to:', workspace);
-      }}
     />
   );
 }
@@ -372,10 +373,12 @@ function WorkspaceManager() {
     currentWorkspace, // Currently selected workspace
     loading, // Loading state
     refreshing, // Refreshing state
+    switching, // True when a workspace switch is in progress
     error, // Error message
     fetchWorkspaces, // Fetch all workspaces
     refreshWorkspaces, // Background refresh
-    setCurrentWorkspace, // Switch workspace
+    setCurrentWorkspace, // Direct workspace set (bypasses onWorkspaceChange)
+    switchToWorkspace, // Full switch flow: onWorkspaceChange first, then set workspace
     createWorkspace, // Create new workspace
     updateWorkspace, // Update workspace
     deleteWorkspace, // Delete workspace
@@ -460,7 +463,7 @@ import { SaaSOSProvider, eventEmitter } from '@buildbase/sdk';
 
 - `user:created` - User account created
 - `user:updated` - User profile updated
-- `workspace:changed` - Workspace switched
+- `workspace:changed` - Workspace switched (fires after switch completes; use `onWorkspaceChange` for prep before switch)
 - `workspace:created` - New workspace created
 - `workspace:updated` - Workspace updated
 - `workspace:deleted` - Workspace deleted
@@ -557,8 +560,15 @@ interface IAuthConfig {
     handleAuthentication: (code: string) => Promise<{ sessionId: string }>;
     onSignOut?: () => Promise<void>;
     handleEvent?: (eventType: EventType, data: EventData) => void | Promise<void>;
+    onWorkspaceChange?: (params: OnWorkspaceChangeParams) => Promise<void>;
   };
 }
+
+interface OnWorkspaceChangeParams {
+  workspace: IWorkspace;
+  user: AuthUser | null;
+  role: string | null; // User's role in this workspace
+}
 ```
 
 ### Validation Requirements
@@ -683,7 +693,7 @@ import { useSaaSWorkspaces } from '@buildbase/sdk';
 import { useEffect } from 'react';
 
 function App() {
-  const { currentWorkspace, setCurrentWorkspace } = useSaaSWorkspaces();
+  const { currentWorkspace, switching } = useSaaSWorkspaces();
 
   useEffect(() => {
     if (currentWorkspace) {
@@ -693,10 +703,15 @@ function App() {
     }
   }, [currentWorkspace]);
 
+  // Show loading during switch (switchingToId !== null)
+  if (switching) return <LoadingOverlay />;
+
   return <YourApp />;
 }
 ```
 
+For token generation or prep before switching, configure `onWorkspaceChange` in auth callbacks (see Quick Start)—it receives `{ workspace, user, role }`.
+
 ### Pattern 6: Error Boundary with Custom Fallback
 
 ```tsx
@@ -863,7 +878,7 @@ A: Yes, as long as you're using React 19+.
 A: Use the `trigger` render prop to fully customize the UI.
 
 **Q: Can I use multiple workspaces simultaneously?**  
-A: No, the SDK manages one current workspace at a time. Switch between workspaces using `setCurrentWorkspace()`.
+A: No, the SDK manages one current workspace at a time. Use `switchToWorkspace()` (runs `onWorkspaceChange` first) or `setCurrentWorkspace()` (direct set, bypasses callback).
 
 **Q: How do I handle offline scenarios?**  
 A: The SDK stores session data in localStorage. Handle offline scenarios in your `handleAuthentication` callback.
@@ -933,9 +948,13 @@ try {
 
 ```tsx
 // ✅ Good
-const { currentWorkspace, setCurrentWorkspace } = useSaaSWorkspaces();
+const { currentWorkspace, switchToWorkspace, switching } = useSaaSWorkspaces();
+// switchToWorkspace: runs onWorkspaceChange first (token gen, etc.)
+// switching: true when switch is in progress
 ```
 
+✅ **Do**: Configure `onWorkspaceChange` in auth callbacks for token generation—receives `{ workspace, user, role }`.
+
 ❌ **Don't**: Manually manage workspace state.
 
 ```tsx
@@ -987,17 +1006,19 @@ const { signIn, status } = useSaaSAuth();
 
 ### 6. Event Handling
 
-✅ **Do**: Handle events in your provider configuration.
+✅ **Do**: Handle events in your provider configuration. Use `onWorkspaceChange` for prep before switch (e.g. generate token), and `handleEvent` for post-switch notifications.
 
 ```tsx
 // ✅ Good
 <SaaSOSProvider
   auth={{
     callbacks: {
+      onWorkspaceChange: async ({ workspace, user, role }) => {
+        await generateTokenForWorkspace(workspace._id, user?.id, role);
+      },
       handleEvent: async (eventType, data) => {
-        // Handle events
         if (eventType === 'workspace:changed') {
-          // Update your app state
+          // Workspace already switched; update app state
         }
       },
     },

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 {
@@ -27,6 +27,12 @@ interface ISubscription {
     cancelAtPeriodEnd: boolean;
     createdAt: string;
     updatedAt: string;
+    plan?: {
+        _id: string;
+        name: string;
+        slug: string;
+        description?: string;
+    };
 }
 interface ISubscriptionItem {
     _id: string;
@@ -209,6 +215,7 @@ type InvoiceStatus = 'draft' | 'open' | 'paid' | 'uncollectible' | 'void';
 interface IInvoice {
     id: string;
     amount_due: number;
+    number: string | null;
     amount_paid: number;
     currency: string;
     status: InvoiceStatus;
@@ -238,6 +245,7 @@ interface IWorkspace {
     roles: string[];
     createdBy: string | IUser;
     features: Record<string, boolean>;
+    subscription?: ISubscription | null;
 }
 interface IWorkspaceFeature {
     _id: string;
@@ -355,6 +363,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 {
@@ -677,6 +696,8 @@ declare const WhenUserFeatureEnabled: (props: IProps) => react.ReactNode;
  */
 declare const WhenUserFeatureDisabled: (props: IProps) => react.ReactNode;
 
+type WorkspaceSettingsSection = 'profile' | 'general' | 'users' | 'subscription' | 'features' | 'danger';
+
 /**
  * Main authentication hook for the SDK.
  * Provides authentication state, user session, and auth actions.
@@ -741,7 +762,7 @@ declare const WhenUserFeatureDisabled: (props: IProps) => react.ReactNode;
 declare function useSaaSAuth(): {
     signIn: () => Promise<void>;
     signOut: () => Promise<void>;
-    openWorkspaceSettings: (section?: "profile" | "general" | "users" | "features" | "danger") => void;
+    openWorkspaceSettings: (section?: WorkspaceSettingsSection) => void;
     isAuthenticated: boolean;
     isLoading: boolean;
     isRedirecting: boolean;
@@ -885,11 +906,6 @@ 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.
@@ -900,11 +916,11 @@ declare function WorkspaceSwitcher(props: {
  * - `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
+ * - `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
+ * - `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
@@ -1002,16 +1018,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<{
@@ -1034,8 +1053,13 @@ 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.
  * Automatically fetches subscription when workspaceId changes.
@@ -1544,185 +1568,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 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);
-    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;
-/**
- * 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 };
-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 };