@buildbase/sdk 0.0.15 → 0.0.18

package/README.md

@@ -10,6 +10,7 @@ A React SDK for [BuildBase](https://www.buildbase.app/) that provides essential
 - [Authentication](#-authentication)
 - [Role-Based Access Control](#-role-based-access-control)
 - [Feature Flags](#️-feature-flags)
+- [Subscription Gates](#-subscription-gates)
 - [User Management](#-user-management)
 - [Workspace Management](#-complete-workspace-management)
 - [Public Pricing (No Login)](#-public-pricing-no-login)
@@ -22,6 +23,7 @@ A React SDK for [BuildBase](https://www.buildbase.app/) that provides essential
 - [Troubleshooting](#-troubleshooting)
 - [API Reference](#-api-reference)
 - [Best Practices](#-best-practices)
+- [Documentation](#further-documentation)
 
 ## 🚀 Features
 
@@ -29,6 +31,7 @@ A React SDK for [BuildBase](https://www.buildbase.app/) that provides essential
 - **🏢 Workspace Management** - Multi-workspace support with switching capabilities
 - **👥 Role-Based Access Control** - User roles and workspace-specific permissions
 - **🎯 Feature Flags** - Workspace-level and user-level feature toggles
+- **📋 Subscription Gates** - Show or hide UI based on current workspace subscription (plan)
 - **👤 User Management** - User attributes and feature flags management
 - **📝 Beta Form** - Pre-built signup/waitlist form component
 - **📡 Event System** - Subscribe to user and workspace events
@@ -315,6 +318,103 @@ function FeatureExample() {
 
 Use the `useUserFeatures` hook to check feature flags programmatically:
 
+## 📋 Subscription Gates
+
+Control UI visibility based on the current workspace’s subscription. Subscription data is loaded once per workspace and refetched when the workspace changes or when the subscription is updated (e.g. upgrade, cancel, resume).
+
+**SubscriptionContextProvider** is included in **SaaSOSProvider** by default, so subscription gates work without extra setup.
+
+### Subscription Gate Components
+
+```tsx
+import { WhenSubscription, WhenNoSubscription, WhenSubscriptionToPlans } from '@buildbase/sdk';
+
+function BillingExample() {
+  return (
+    <div>
+      {/* Show when workspace has any active subscription */}
+      <WhenSubscription>
+        <BillingSettings />
+      </WhenSubscription>
+
+      {/* Show when workspace has no subscription */}
+      <WhenNoSubscription>
+        <UpgradePrompt />
+      </WhenNoSubscription>
+
+      {/* Show only when subscribed to specific plans (by slug, case-insensitive) */}
+      <WhenSubscriptionToPlans plans={['pro', 'enterprise']}>
+        <AdvancedAnalytics />
+      </WhenSubscriptionToPlans>
+    </div>
+  );
+}
+```
+
+| Component                 | Renders when                                                         |
+| ------------------------- | -------------------------------------------------------------------- |
+| `WhenSubscription`        | Current workspace has an active subscription (any plan); not loading |
+| `WhenNoSubscription`      | Current workspace has no subscription (or no workspace); not loading |
+| `WhenSubscriptionToPlans` | Current workspace is subscribed to one of the given plan slugs       |
+
+All gates must be used inside **SubscriptionContextProvider** (included in SaaSOSProvider). By default they return `null` while loading or when the condition is not met. You can pass optional **loadingComponent** (component/element to show while loading) and **fallbackComponent** (component/element to show when condition is not met):
+
+```tsx
+<WhenSubscription
+  loadingComponent={<Skeleton className="h-20" />}
+  fallbackComponent={<UpgradePrompt />}
+>
+  <BillingSettings />
+</WhenSubscription>
+
+<WhenSubscriptionToPlans
+  plans={['pro', 'enterprise']}
+  loadingComponent={<Spinner />}
+  fallbackComponent={<p>Upgrade to Pro or Enterprise to access this feature.</p>}
+>
+  <AdvancedAnalytics />
+</WhenSubscriptionToPlans>
+```
+
+### useSubscriptionContext
+
+Use the hook when you need subscription data or a manual refetch (e.g. after returning from Stripe checkout):
+
+```tsx
+import { useSubscriptionContext } from '@buildbase/sdk';
+
+function SubscriptionStatus() {
+  const { response, loading, refetch } = useSubscriptionContext();
+
+  if (loading) return <Spinner />;
+  if (!response?.subscription) return <p>No active subscription</p>;
+
+  const plan = response.plan ?? response.subscription?.plan;
+  return (
+    <div>
+      <p>Plan: {plan?.name ?? plan?.slug}</p>
+      <button onClick={() => refetch()}>Refresh</button>
+    </div>
+  );
+}
+```
+
+| Property   | Type                            | Description                                            |
+| ---------- | ------------------------------- | ------------------------------------------------------ |
+| `response` | `ISubscriptionResponse \| null` | Current subscription data for the current workspace    |
+| `loading`  | `boolean`                       | True while subscription is being fetched               |
+| `refetch`  | `() => Promise<void>`           | Manually refetch subscription (e.g. after plan change) |
+
+**When subscription refetches**
+
+- When the current workspace changes (automatic).
+- When subscription is updated via SDK (e.g. `useUpdateSubscription`, cancel, resume) — refetch is triggered automatically.
+- When you call `refetch()` (e.g. after redirect from checkout).
+
+### Feature Flags Hook
+
+Use the `useUserFeatures` hook to check feature flags programmatically:
+
 ```tsx
 import { useUserFeatures } from '@buildbase/sdk';
 
@@ -375,6 +475,7 @@ function WorkspaceManager() {
     loading, // Loading state
     refreshing, // Refreshing state
     switching, // True when a workspace switch is in progress
+    switchingToId, // Workspace ID currently being switched to (null when not switching)
     error, // Error message
     fetchWorkspaces, // Fetch all workspaces
     refreshWorkspaces, // Background refresh
@@ -461,12 +562,12 @@ function PublicPricingPage() {
 }
 ```
 
-| Prop | Type | Description |
-|------|------|-------------|
-| `slug` | `string` | Plan group slug (e.g. 'main-pricing', 'enterprise') |
-| `children` | `(details) => ReactNode` | Render prop receiving `{ loading, error, items, plans, refetch }` |
-| `loadingFallback` | `ReactNode` | Custom loading UI (defaults to skeleton) |
-| `errorFallback` | `(error: string) => ReactNode` | Custom error UI |
+| Prop              | Type                           | Description                                                       |
+| ----------------- | ------------------------------ | ----------------------------------------------------------------- |
+| `slug`            | `string`                       | Plan group slug (e.g. 'main-pricing', 'enterprise')               |
+| `children`        | `(details) => ReactNode`       | Render prop receiving `{ loading, error, items, plans, refetch }` |
+| `loadingFallback` | `ReactNode`                    | Custom loading UI (defaults to skeleton)                          |
+| `errorFallback`   | `(error: string) => ReactNode` | Custom error UI                                                   |
 
 **Response shape**: `items` = subscription item definitions (features, limits, quotas with category); `plans` = plan versions with `pricing`, `quotas`, `features`, `limits`.
 
@@ -539,41 +640,7 @@ import { SaaSOSProvider, eventEmitter } from '@buildbase/sdk';
 
 ## 🛡️ Error Handling
 
-The SDK provides comprehensive error handling:
-
-```tsx
-import { ErrorBoundary, SDKError, handleError, errorHandler } from '@buildbase/sdk';
-
-// Wrap your app with ErrorBoundary
-function App() {
-  return (
-    <ErrorBoundary>
-      <YourApp />
-    </ErrorBoundary>
-  );
-}
-
-// Configure error handler
-errorHandler.configure({
-  enableConsoleLogging: true,
-  showUserNotifications: false,
-  onError: (error, context) => {
-    // Custom error handling
-    console.error('SDK Error:', error, context);
-  },
-});
-
-// Use handleError in your code
-try {
-  // Some operation
-} catch (error) {
-  handleError(error, {
-    component: 'MyComponent',
-    action: 'handleSubmit',
-    metadata: { userId: '123' },
-  });
-}
-```
+The SDK handles errors internally: API failures, auth errors, and component errors are logged and surfaced through hook states (e.g. `error` from `useSaaSWorkspaces`) and callbacks. Wrap your app in an error boundary of your choice to catch React errors. For failed operations, check the `error` property on hooks and handle it in your UI (e.g. toast or inline message).
 
 ## ⚙️ Settings
 
@@ -595,6 +662,52 @@ function SettingsExample() {
 
 ## 📚 API Reference
 
+### Central APIs
+
+All SDK API clients extend a shared base class and are exported from the package:
+
+| Export           | Purpose                                                                         |
+| ---------------- | ------------------------------------------------------------------------------- |
+| `BaseApi`        | Abstract base (URL, auth, `fetchJson`/`fetchResponse`) – extend for custom APIs |
+| `IBaseApiConfig` | Config type: `serverUrl`, `version`, optional `orgId`                           |
+| `UserApi`        | User attributes and features                                                    |
+| `WorkspaceApi`   | Workspaces, subscription, invoices, users                                       |
+| `SettingsApi`    | Organization settings                                                           |
+
+Use the hooks (`useUserApi`, `useWorkspaceApi`, etc.) for a ready-made instance with OS config, or instantiate with your own config:
+
+```tsx
+import { UserApi, WorkspaceApi, SettingsApi, useSaaSOs } from '@buildbase/sdk';
+
+// Via hook (uses OS config from context)
+const api = useWorkspaceApi(); // or useUserApi(), etc.
+
+// Or instantiate with config
+const os = useSaaSOs();
+const workspaceApi = new WorkspaceApi({
+  serverUrl: os.serverUrl,
+  version: os.version,
+  orgId: os.orgId,
+});
+```
+
+### Hooks
+
+Prefer these SDK hooks for state and operations instead of `useAppSelector`:
+
+| Hook                       | Purpose                                                                                                 |
+| -------------------------- | ------------------------------------------------------------------------------------------------------- |
+| `useSaaSAuth()`            | Auth state (user, session, status), signIn, signOut, openWorkspaceSettings                              |
+| `useSaaSWorkspaces()`      | Workspaces, currentWorkspace, loading, switching/switchingToId, CRUD and switch actions                 |
+| `useSaaSOs()`              | OS config (serverUrl, version, orgId, auth, settings) when you need the full config object              |
+| `useSaaSSettings()`        | Organization settings and getSettings (prefer this when you only need settings)                         |
+| `useUserAttributes()`      | User attributes and update/refresh                                                                      |
+| `useUserFeatures()`        | User feature flags                                                                                      |
+| `useSubscriptionContext()` | Subscription for current workspace (response, loading, refetch); use inside SubscriptionContextProvider |
+| Subscription hooks         | `usePublicPlans`, `useSubscription`, `usePlanGroup`, etc.                                               |
+
+Using hooks keeps your code stable if internal state shape changes and avoids direct Redux/context coupling.
+
 ### Enums
 
 - `ApiVersion` - API version enum (currently only `V1`)
@@ -604,6 +717,11 @@ function SettingsExample() {
 
 All TypeScript types are exported for type safety. See the [TypeScript definitions](./dist/index.d.ts) for complete type information.
 
+### Further documentation
+
+- [Architecture](docs/ARCHITECTURE.md) – Layers, APIs (BaseApi, UserApi, WorkspaceApi, SettingsApi), state, auth flow
+- [Error codes](docs/ERROR_CODES.md) – SDK error codes and HTTP status mappings
+
 ## ⚙️ Configuration Reference
 
 ### SaaSOSProvider Props
@@ -752,6 +870,32 @@ function Dashboard() {
 }
 ```
 
+### Pattern 4b: Subscription-Gated UI
+
+```tsx
+import { WhenSubscription, WhenNoSubscription, WhenSubscriptionToPlans } from '@buildbase/sdk';
+
+function BillingPage() {
+  return (
+    <div>
+      <WhenNoSubscription>
+        <UpgradePrompt />
+      </WhenNoSubscription>
+
+      <WhenSubscription>
+        <BillingSettings />
+      </WhenSubscription>
+
+      <WhenSubscriptionToPlans plans={['pro', 'enterprise']}>
+        <AdvancedBillingFeatures />
+      </WhenSubscriptionToPlans>
+    </div>
+  );
+}
+```
+
+SubscriptionContextProvider is included in SaaSOSProvider by default, so no extra wrapper is needed.
+
 ### Pattern 5: Handling Workspace Changes
 
 ```tsx
@@ -769,7 +913,7 @@ function App() {
     }
   }, [currentWorkspace]);
 
-  // Show loading during switch (switchingToId !== null)
+  // Show loading during switch; use switchingToId for the workspace ID being switched to
   if (switching) return <LoadingOverlay />;
 
   return <YourApp />;
@@ -778,37 +922,9 @@ function App() {
 
 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
-import { ErrorBoundary, SDKError } from '@buildbase/sdk';
-
-function CustomErrorFallback({ error, resetError }) {
-  if (error instanceof SDKError) {
-    return (
-      <div>
-        <h2>SDK Error: {error.message}</h2>
-        <button onClick={resetError}>Try Again</button>
-      </div>
-    );
-  }
-
-  return (
-    <div>
-      <h2>Something went wrong</h2>
-      <button onClick={resetError}>Reload</button>
-    </div>
-  );
-}
+### Pattern 6: Error Boundary
 
-function App() {
-  return (
-    <ErrorBoundary fallback={CustomErrorFallback}>
-      <YourApp />
-    </ErrorBoundary>
-  );
-}
-```
+Wrap your app (or a subtree) with an error boundary to catch React errors and show a fallback. Use your framework’s boundary (e.g. React’s `ErrorBoundary` or Next.js error UI). In catch blocks for async operations, show user feedback (e.g. toast or inline message) using the `error` state from hooks.
 
 ## 🔧 Troubleshooting
 
@@ -984,39 +1100,33 @@ function App() {
 
 ### 2. Error Handling
 
-✅ **Do**: Wrap your app with `ErrorBoundary` and configure error handler.
+✅ **Do**: Wrap your app with an error boundary (your framework’s or React’s) to catch render errors.
 
-```tsx
-// ✅ Good
-<ErrorBoundary>
-  <SaaSOSProvider {...config}>
-    <App />
-  </SaaSOSProvider>
-</ErrorBoundary>
-```
+✅ **Do**: Handle async failures using the `error` from hooks and show user feedback (e.g. toast or inline message).
 
-✅ **Do**: Use `handleError` for custom error handling.
+### 3. State Access: Prefer SDK Hooks Over useAppSelector
+
+✅ **Do**: Use SDK hooks for auth, workspace, and OS state.
 
 ```tsx
-try {
-  await someOperation();
-} catch (error) {
-  handleError(error, {
-    component: 'MyComponent',
-    action: 'operation',
-  });
-}
+// ✅ Good – use hooks
+const { user, isAuthenticated } = useSaaSAuth();
+const { workspaces, currentWorkspace, switchingToId } = useSaaSWorkspaces();
+const { settings } = useSaaSSettings();
+const os = useSaaSOs(); // when you need full OS config (serverUrl, version, orgId, etc.)
 ```
 
-### 3. Workspace Management
+❌ **Don't**: Use `useAppSelector(state => state.auth)` or similar in app code—prefer the hooks above so the SDK can evolve internal state without breaking you.
+
+### 4. Workspace Management
 
 ✅ **Do**: Use `useSaaSWorkspaces` hook for workspace operations.
 
 ```tsx
 // ✅ Good
-const { currentWorkspace, switchToWorkspace, switching } = useSaaSWorkspaces();
+const { currentWorkspace, switchToWorkspace, switching, switchingToId } = useSaaSWorkspaces();
 // switchToWorkspace: runs onWorkspaceChange first (token gen, etc.)
-// switching: true when switch is in progress
+// switching: true when switch is in progress; switchingToId: workspace ID being switched to
 ```
 
 ✅ **Do**: Configure `onWorkspaceChange` in auth callbacks for token generation—receives `{ workspace, user, role }`.
@@ -1028,7 +1138,7 @@ const { currentWorkspace, switchToWorkspace, switching } = useSaaSWorkspaces();
 const [workspace, setWorkspace] = useState(null); // Don't do this
 ```
 
-### 4. Feature Flags
+### 5. Feature Flags
 
 ✅ **Do**: Use feature flag components for conditional rendering.
 
@@ -1049,7 +1159,7 @@ if (isFeatureEnabled('premium')) {
 }
 ```
 
-### 5. Authentication
+### 6. Authentication
 
 ✅ **Do**: Use `WhenAuthenticated`/`WhenUnauthenticated` for route protection.
 
@@ -1070,7 +1180,7 @@ const { signIn, status } = useSaaSAuth();
 </button>;
 ```
 
-### 6. Event Handling
+### 7. Event Handling
 
 ✅ **Do**: Handle events in your provider configuration. Use `onWorkspaceChange` for prep before switch (e.g. generate token), and `handleEvent` for post-switch notifications.
 
@@ -1092,7 +1202,7 @@ const { signIn, status } = useSaaSAuth();
 >
 ```
 
-### 7. TypeScript
+### 8. TypeScript
 
 ✅ **Do**: Use TypeScript for better type safety.
 
@@ -1105,7 +1215,7 @@ function MyComponent({ workspace }: { workspace: IWorkspace }) {
 }
 ```
 
-### 8. Performance
+### 9. Performance
 
 ✅ **Do**: Memoize expensive computations.