@buildbase/sdk 0.0.54 → 0.0.55

package/dist/react/index.mjs

@@ -1,2 +1,2 @@
 "use client";
-export{az as ApiVersion,aA as AuthApi,aB as AuthStatus,m as BBAction,aC as BBScreen,n as BBStatus,aD as BB_PARAM,aE as BaseApi,aF as BetaForm,ab as BillingIntervals,aG as CURRENCY_DISPLAY,aH as CURRENCY_FLAG,C as ConnectedAgents,aI as ConnectedAgentsApi,aJ as CreditActionsProvider,aK as CreditBalance,aL as CreditBalanceContextProvider,aM as CreditBucketSource,aN as CreditBucketStatus,aO as CreditStorePage,t as CreditTransactionType,aP as DEFAULT_ROLE_PERMISSIONS,ac as DunningState,E as EmptyState,aQ as EventEmitter,aR as FullScreenLoader,$ as InvoiceStatuses,L as LoadingState,aS as PLAN_CURRENCY_CODES,aT as PLAN_CURRENCY_OPTIONS,aU as PUSH_SERVICE_WORKER_SCRIPT,P as Permission,aV as PricingPage,aW as PushApi,aX as PushNotificationProvider,aY as QuotaUsageContextProvider,aZ as SDKEvent,ax as SETTINGS_SCREENS,a_ as SUPPORTED_LOCALES,a$ as SaaSOSProvider,q as SectionHeader,b0 as SettingsApi,aq as SettingsScreen,as as SidebarNavItem,ar as SidebarNavSection,p as StatusBanner,b1 as SubscriptionContextProvider,ae as SubscriptionItemType,a7 as SubscriptionStatus,b2 as UserApi,b3 as WhenAuthenticated,b4 as WhenCreditsAvailable,b5 as WhenCreditsExhausted,b6 as WhenCreditsLow,b7 as WhenNoSubscription,b8 as WhenNotTrialing,b9 as WhenPermission,ba as WhenQuotaAvailable,bb as WhenQuotaExhausted,bc as WhenQuotaOverage,bd as WhenQuotaThreshold,be as WhenRoles,bf as WhenSubscription,bg as WhenSubscriptionToPlans,bh as WhenTrialEnding,bi as WhenTrialing,bj as WhenUnauthenticated,bk as WhenUserFeatureDisabled,bl as WhenUserFeatureEnabled,bm as WhenWorkspaceFeatureDisabled,bn as WhenWorkspaceFeatureEnabled,bo as WhenWorkspaceRoles,bp as WorkspaceApi,bq as WorkspaceSwitcher,br as calculateBillableSeats,bs as calculateSeatOverageCents,bt as calculateTotalSubscriptionCents,bu as cleanBBParams,bv as clearAuthIntent,bw as consumeAuthIntent,bx as createBBUrl,ai as createCheckoutRedirectUrls,r as createCreditPurchaseRedirectUrls,by as eventEmitter,bz as formatCents,bA as formatOverageRate,bB as formatOverageRateWithLabel,bC as formatQuotaIncludedOverage,bD as formatQuotaWithPrice,ay as getAvailableCurrenciesFromPlans,a8 as getBasePriceCents,a6 as getBillingIntervalAndCurrencyFromPriceId,O as getCurrencyFlag,g as getCurrencySymbol,bE as getDisplayCurrency,aa as getPerSeatPriceCents,bF as getPricingVariant,ag as getQuotaDisplayValue,af as getQuotaDisplayWithVariant,am as getQuotaOverageCents,bG as getQuotaUnitLabelFromName,a9 as getSeatPricing,ah as getStripePriceIdForInterval,bH as hasPermission,o as invalidateCreditBalance,bI as invalidateQuotaUsage,aj as invalidateSubscription,bJ as isZeroDecimalCurrency,au as mergeUIConfig,bK as minorAmountToDisplay,bL as readBBParams,bM as resolveMaxUsers,bN as resolvePermissions,s as safeRedirect,bO as saveAuthIntent,bP as useAllQuotaUsage,a4 as useBillingPortal,a2 as useCancelSubscription,bQ as useConnectedAgents,bR as useConnectedAgentsApi,bS as useConsumeCredits,a1 as useCreateCheckoutSession,bT as useCreditBalance,h as useCreditBalanceContext,i as useCreditPackages,k as useCreditTransactions,j as useExpiringCredits,bU as useFullScreenLoader,bV as useInvoice,_ as useInvoices,e as usePermissions,bW as usePlanGroup,a5 as usePlanGroupVersions,bX as usePublicCreditPackages,bY as usePublicPlanGroupVersion,bZ as usePublicPlans,l as usePurchaseCredits,X as usePushNotifications,ak as useQuotaUsageContext,b_ as useQuotaUsageStatus,b$ as useRecordUsage,a3 as useResumeSubscription,an as useSaaSAuth,c0 as useSaaSOs,z as useSaaSSettings,y as useSaaSWorkspaces,ao as useSeatStatus,c1 as useSubscription,al as useSubscriptionContext,a0 as useSubscriptionManagement,u as useTranslation,c2 as useTrialStatus,at as useUIConfig,f as useUIVisibility,c3 as useUpdateSubscription,c4 as useUsageLogs,c5 as useUserAttributes,c6 as useUserFeatures,c7 as validateInvite,c8 as validateRedirectUrl,w as workspaceSettingsManager}from"./chunks/react-CC6T7Zky.mjs";import"react/jsx-runtime";import"react";import"clsx";import"tailwind-merge";import"intl-messageformat";import"@hookform/resolvers/zod";import"react-hook-form";import"@radix-ui/react-slot";import"class-variance-authority";import"lucide-react";import"@radix-ui/react-label";import"zod";import"@radix-ui/react-avatar";import"@radix-ui/react-dialog";import"@radix-ui/react-icons";import"@radix-ui/react-radio-group";import"@radix-ui/react-scroll-area";import"@radix-ui/react-separator";
+export{aF as ApiVersion,aG as AuthApi,aH as AuthStatus,o as BBAction,aI as BBScreen,p as BBStatus,aJ as BB_PARAM,aK as BaseApi,aL as BetaForm,a6 as BillingIntervals,aM as BuildBaseProvider,aN as CURRENCY_DISPLAY,aO as CURRENCY_FLAG,aP as ConnectMcpGuide,C as ConnectedAgents,aQ as ConnectedAgentsApi,aR as CreditActionsProvider,aS as CreditBalance,aT as CreditBalanceContextProvider,aU as CreditBucketSource,aV as CreditBucketStatus,aW as CreditStorePage,y as CreditTransactionType,aX as DEFAULT_ROLE_PERMISSIONS,al as DunningState,E as EmptyState,aY as EventEmitter,aZ as FullScreenLoader,a4 as InvoiceStatuses,L as LoadingState,a_ as PLAN_CURRENCY_CODES,a$ as PLAN_CURRENCY_OPTIONS,b0 as PUSH_SERVICE_WORKER_SCRIPT,P as Permission,b1 as PricingPage,b2 as PushApi,b3 as PushNotificationProvider,b4 as QuotaUsageContextProvider,b5 as SDKEvent,aC as SETTINGS_SCREENS,b6 as SUPPORTED_LOCALES,aM as SaaSOSProvider,s as SectionHeader,b7 as SettingsApi,av as SettingsScreen,ax as SidebarNavItem,aw as SidebarNavSection,r as StatusBanner,b8 as SubscriptionContextProvider,a7 as SubscriptionItemType,aa as SubscriptionStatus,b9 as UserApi,ba as WhenAuthenticated,bb as WhenCreditsAvailable,bc as WhenCreditsExhausted,bd as WhenCreditsLow,be as WhenNoSubscription,bf as WhenNotTrialing,bg as WhenPermission,bh as WhenQuotaAvailable,bi as WhenQuotaExhausted,bj as WhenQuotaOverage,bk as WhenQuotaThreshold,bl as WhenRoles,bm as WhenSubscription,bn as WhenSubscriptionToPlans,bo as WhenTrialEnding,bp as WhenTrialing,bq as WhenUnauthenticated,br as WhenUserFeatureDisabled,bs as WhenUserFeatureEnabled,bt as WhenWorkspaceFeatureDisabled,bu as WhenWorkspaceFeatureEnabled,bv as WhenWorkspaceRoles,bw as WorkspaceApi,bx as WorkspaceSwitcher,by as calculateBillableSeats,bz as calculateSeatOverageCents,bA as calculateTotalSubscriptionCents,bB as cleanBBParams,bC as clearAuthIntent,bD as consumeAuthIntent,bE as createBBUrl,an as createCheckoutRedirectUrls,v as createCreditPurchaseRedirectUrls,bF as eventEmitter,bG as fillMcpTemplate,bH as formatCents,f as formatMinorAmountIntl,bI as formatOverageRate,bJ as formatOverageRateWithLabel,bK as formatQuotaIncludedOverage,bL as formatQuotaWithPrice,aE as getAvailableCurrenciesFromPlans,ai as getBasePriceCents,ah as getBillingIntervalAndCurrencyFromPriceId,e as getCurrencyDecimals,T as getCurrencyFlag,g as getCurrencySymbol,bM as getDisplayCurrency,ak as getPerSeatPriceCents,aD as getPricingVariant,a9 as getQuotaDisplayValue,a8 as getQuotaDisplayWithVariant,ar as getQuotaOverageCents,bN as getQuotaUnitLabelFromName,aj as getSeatPricing,am as getStripePriceIdForInterval,bO as hasPermission,q as invalidateCreditBalance,bP as invalidateQuotaUsage,ao as invalidateSubscription,bQ as isZeroDecimalCurrency,bR as mcpServerKey,az as mergeUIConfig,bS as minorAmountToDisplay,bT as readBBParams,bU as resolveMaxUsers,bV as resolvePermissions,x as safeRedirect,bW as saveAuthIntent,bX as useAllQuotaUsage,af as useBillingPortal,ad as useCancelSubscription,bY as useConnectedAgents,bZ as useConnectedAgentsApi,b_ as useConsumeCredits,ac as useCreateCheckoutSession,b$ as useCreditBalance,j as useCreditBalanceContext,k as useCreditPackages,m as useCreditTransactions,l as useExpiringCredits,c0 as useFullScreenLoader,c1 as useInvoice,a2 as useInvoices,c2 as useMcpConnection,h as usePermissions,c3 as usePlanGroup,ag as usePlanGroupVersions,c4 as usePublicCreditPackages,c5 as usePublicPlanGroupVersion,c6 as usePublicPlans,n as usePurchaseCredits,_ as usePushNotifications,ap as useQuotaUsageContext,c7 as useQuotaUsageStatus,c8 as useRecordUsage,ae as useResumeSubscription,as as useSaaSAuth,c9 as useSaaSOs,G as useSaaSSettings,F as useSaaSWorkspaces,at as useSeatStatus,ca as useSubscription,aq as useSubscriptionContext,ab as useSubscriptionManagement,u as useTranslation,cb as useTrialStatus,ay as useUIConfig,i as useUIVisibility,cc as useUpdateSubscription,cd as useUsageLogs,ce as useUserAttributes,cf as useUserFeatures,cg as validateInvite,ch as validateRedirectUrl,w as workspaceSettingsManager}from"./chunks/react-CXCk05WI.mjs";import"react/jsx-runtime";import"react";import"clsx";import"tailwind-merge";import"intl-messageformat";import"@hookform/resolvers/zod";import"react-hook-form";import"@radix-ui/react-slot";import"class-variance-authority";import"lucide-react";import"@radix-ui/react-label";import"zod";import"@radix-ui/react-avatar";import"@radix-ui/react-dialog";import"@radix-ui/react-icons";import"@radix-ui/react-radio-group";import"@radix-ui/react-scroll-area";import"@radix-ui/react-separator";import"@radix-ui/react-accordion";

package/docs/ARCHITECTURE.md

@@ -0,0 +1,419 @@
+# SDK Architecture Documentation
+
+This document describes the internal architecture and design decisions of the BuildBase SDK.
+
+## Overview
+
+The BuildBase SDK is a React-based SDK that provides authentication, workspace management, user management, and subscription features. It uses React Context for state management and follows a provider-based architecture.
+
+## Architecture Layers
+
+### 1. Provider Layer
+
+The SDK uses a nested provider structure:
+
+```
+SaaSOSProvider (root)
+  ├── TranslationProvider (i18n)
+  ├── SDKContextProvider (context management)
+  ├── AuthProviderWrapper (authentication)
+  ├── PortalProvider (portal rendering)
+  ├── ContextConfigProvider (OS configuration)
+  ├── CheckoutConfigProvider (Stripe checkout params)
+  ├── PermissionConfigProvider (app permissions)
+  ├── UserProvider (user attributes/features)
+  ├── SubscriptionContextProvider (subscription for current workspace; powers subscription gates)
+  ├── QuotaUsageContextProvider (quota usage; powers quota gates)
+  ├── CreditBalanceContextProvider (credit balance; powers credit gates)
+  ├── PushNotificationProvider (browser push)
+  └── WorkspaceSettingsProvider (workspace settings UI)
+```
+
+**Design Decision**: Nested providers allow for:
+
+- Clear separation of concerns
+- Independent feature enablement
+- Proper dependency ordering (auth before workspace, etc.)
+
+### 2. Context Layer
+
+The SDK uses multiple React contexts for state management:
+
+#### AuthContext
+
+- **Purpose**: Manages authentication state and session
+- **State**: `{ session: AuthSession | null, status: AuthStatus }`
+- **Design**: Single source of truth for auth state. Status enum drives all auth flags (derived, not stored).
+
+#### OSContext
+
+- **Purpose**: Manages SDK configuration (serverUrl, version, orgId, settings)
+- **State**: `{ serverUrl, version, orgId, settings, auth }`
+- **Design**: Immutable config that rarely changes after initialization.
+
+#### WorkspaceContext
+
+- **Purpose**: Manages workspace state and operations
+- **State**: `{ workspaces[], currentWorkspace, loading, error, ... }`
+- **Design**: Centralized workspace state with optimistic updates.
+
+#### SDKContext
+
+- **Purpose**: Combines all contexts into a single provider
+- **Design**: Reduces provider nesting and provides unified state access.
+
+#### SubscriptionContext
+
+- **Purpose**: Provides subscription data for the current workspace to subscription gate components
+- **State**: `{ response: ISubscriptionResponse | null, loading: boolean, refetch: () => Promise<void> }`
+- **Design**: Read-only; data comes from `useSubscription(currentWorkspace?._id)`. Refetches when workspace changes or when subscription is invalidated (e.g. after plan update, cancel, resume). Internal invalidation notifier allows mutation hooks to trigger a refetch so gates stay in sync.
+
+**Design Decision**: Multiple contexts instead of single context:
+
+- Better performance (components only re-render when their context changes)
+- Clearer separation of concerns
+- Easier to test individual features
+
+### 3. API Layer
+
+The SDK uses a **central base class + domain APIs** pattern. All domain API classes extend `BaseApi` for shared URL building, auth headers, and request/response handling.
+
+#### BaseApi (`src/lib/api-base.ts`)
+
+- **Purpose**: Abstract base for all SDK API clients
+- **Provides**: `baseUrl`, `getAuthHeaders()`, `url(path)`, `fetchJson<T>()`, `fetchResponse()`, `throwResponseError()`, `unwrapResponse<T>()`
+- **Config**: `IBaseApiConfig` (serverUrl, version, optional orgId, onUnauthorized, timeout, maxRetries, debug, onError)
+
+#### Domain APIs (extend BaseApi)
+
+| Class            | Location                         | Purpose                                   |
+| ---------------- | -------------------------------- | ----------------------------------------- |
+| **UserApi**      | `src/providers/user/api.ts`      | User attributes, user features            |
+| **WorkspaceApi** | `src/providers/workspace/api.ts` | Workspaces, subscription, invoices, users |
+| **SettingsApi**  | `src/providers/os/api.ts`        | Organization settings                     |
+
+All are exported from the package; consumers typically use the high-level hooks (e.g. `useSaaSWorkspaces`, `useUserAttributes`) or instantiate API classes with config from `useSaaSOs()`.
+
+#### API utilities (shared helpers)
+
+- **Location**: `src/lib/api-utils.ts`
+- **Functions**: `safeFetch`, `handleApiResponse`, `getErrorMessage`, `isAbortError`, `fetchWithTimeout`
+- **Error helpers** (`src/lib/error-handler.ts`): `handleError`, `getHookErrorMessage`, `createSDKError`
+
+#### Currency, pricing variant & quota utilities
+
+Multi-currency plans use **pricing variants** (`IPricingVariant`) and **per-interval quotas** (`IQuotaByInterval`). These modules are in `src/api/` and are exported from the package:
+
+| Module                    | Purpose                                                                                                                                                                                                                                                                                                                   |
+| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **currency-utils**        | `CURRENCY_DISPLAY`, `CURRENCY_FLAG`, `PLAN_CURRENCY_CODES`, `PLAN_CURRENCY_OPTIONS`, `getCurrencySymbol`, `getCurrencyFlag`, `formatCents`, `formatOverageRate`, `formatOverageRateWithLabel`, `formatQuotaIncludedOverage`, `getQuotaUnitLabelFromName`                                                                  |
+| **pricing-variant-utils** | `getPricingVariant`, `getBasePriceCents`, `getStripePriceIdForInterval`, `getQuotaOverageCents`, `getQuotaDisplayWithVariant`, `getAvailableCurrenciesFromPlans`, `getDisplayCurrency`, `getBillingIntervalAndCurrencyFromPriceId`; types: `IPricingVariant`, `PlanVersionWithPricingVariants`, `QuotaDisplayWithOverage` |
+| **quota-utils**           | `getQuotaDisplayValue`, `formatQuotaWithPrice`; types: `QuotaDisplayValue`, `FormatQuotaWithPriceOptions`                                                                                                                                                                                                                 |
+
+Plan and subscription types use `IPlanVersion.pricingVariants` (instead of single `basePricing`/`stripePrices`) and `IQuotaByInterval` / `IQuotaIntervalValue` for quotas and overages per billing interval.
+
+**Design Decision**: Central base class + domain APIs:
+
+- Single place for URL building, auth, and fetch behavior
+- Easy to add new domains (extend BaseApi)
+- Consistent error handling and logging
+
+### 4. Hook Layer
+
+The SDK exposes hooks for consuming context and performing operations. **Prefer these hooks over `useAppSelector`** for state access so the SDK can evolve internal state without breaking consumers.
+
+#### Auth Hooks
+
+- `useSaaSAuth()`: Main auth hook (user, session, status, signIn, signOut, openWorkspaceSettings)
+
+#### OS Hooks
+
+- `useSaaSOs()`: Full OS config (serverUrl, version, orgId, auth, settings). Use when you need the config object.
+- `useSaaSSettings()`: Organization settings and getSettings. Prefer this when you only need settings.
+
+#### Workspace Hooks
+
+- `useSaaSWorkspaces()`: Main workspace management hook (workspaces, currentWorkspace, loading, switching, switchingToId, CRUD and switch actions)
+- Subscription hooks: `useSubscription`, `usePlanGroup`, etc.
+
+#### Subscription Context Hook
+
+- `useSubscriptionContext()`: Returns subscription for current workspace (response, loading, refetch). Used by subscription gate components; available to app code when subscription data or manual refetch is needed. Must be used within SubscriptionContextProvider.
+
+#### User Hooks
+
+- `useUserAttributes()`: User attributes access
+- `useUserFeatures()`: User feature flags
+
+**Design Decision**: Hooks pattern:
+
+- Familiar React API
+- Automatic re-renders on state changes
+- Easy to use in functional components
+- Type-safe with TypeScript
+- Single public API for state; internal use of `useAppSelector` is limited to hook/context implementation
+
+### 5. Component Layer
+
+The SDK provides conditional rendering components:
+
+#### Auth Components
+
+- `WhenAuthenticated`: Renders when user is authenticated
+- `WhenUnauthenticated`: Renders when user is not authenticated
+
+#### Role Components
+
+- `WhenRoles`: Renders based on user's global role
+- `WhenWorkspaceRoles`: Renders based on user's workspace role
+
+#### Feature Components
+
+- `WhenUserFeatureEnabled/Disabled`: Renders based on user feature flags
+- `WhenWorkspaceFeatureEnabled/Disabled`: Renders based on workspace feature flags
+
+#### Subscription Gate Components
+
+- `WhenSubscription`: Renders when current workspace has an active subscription (any plan)
+- `WhenNoSubscription`: Renders when current workspace has no subscription
+- `WhenSubscriptionToPlans`: Renders when current workspace is subscribed to one of the given plan slugs
+
+All subscription gates consume `useSubscriptionContext()` and must be used within `SubscriptionContextProvider` (included in SaaSOSProvider by default).
+
+**Design Decision**: Conditional components:
+
+- Declarative API for feature gating
+- Reduces boilerplate in consumer apps
+- Type-safe with TypeScript
+
+## State Management
+
+### Context-Based State (No Redux)
+
+**Decision**: Use React Context instead of Redux.
+
+**Rationale**:
+
+- Simpler for SDK consumers (no Redux setup required)
+- Less bundle size
+- Sufficient for SDK's state management needs
+- Better integration with React 19
+
+### State Updates
+
+State updates use reducer pattern:
+
+```typescript
+// Example: AuthContext reducer
+function authReducer(state: IAuthState, action: AuthAction): IAuthState {
+  switch (action.type) {
+    case 'AUTHENTICATION_STARTED':
+      return { ...state, status: AuthStatus.redirecting };
+    // ...
+  }
+}
+```
+
+**Design Decision**: Reducer pattern:
+
+- Predictable state updates
+- Easy to debug (action-based)
+- Type-safe with TypeScript
+
+### Derived State
+
+Some state is derived rather than stored:
+
+```typescript
+// Auth flags are derived from status
+const flags = getAuthFlags(auth.status);
+// Returns: { isLoading, isAuthenticated, isRedirecting }
+```
+
+**Design Decision**: Derived state:
+
+- Single source of truth (status enum)
+- Prevents state inconsistencies
+- Reduces state size
+
+## Authentication Flow
+
+### OAuth Flow
+
+1. User calls `signIn()`
+2. SDK redirects to OAuth provider
+3. User authenticates with provider
+4. Provider redirects back with `?code=...`
+5. SDK exchanges code for session
+6. Session stored in localStorage and context
+
+### Session Management
+
+- **Source of truth**: httpOnly cookie (set by your server, not readable by JS)
+- **Hydration**: On mount, SDK calls `getSession()` callback to restore the session from your server endpoint
+- **Validation**: Session validated by fetching user profile with the sessionId
+- **Expiration**: 401 responses trigger `onSessionExpired` callback (during hydration and mid-session via `onUnauthorized` interceptor in BaseApi)
+- **Guards**: Component-scoped refs prevent duplicate hydration across mount/remount cycles
+
+**Design Decision**: httpOnly cookie + callback pattern (similar to next-auth):
+
+- Secure: session token not accessible to JS (XSS-safe)
+- Flexible: server controls cookie lifetime, httpOnly, secure flags
+- Framework-agnostic: works with any server (Next.js, Express, Hono)
+
+### Workspace Switching
+
+- **Entry point**: `switchToWorkspace(id)` calls auth callback `onWorkspaceChange({ workspace, user, role })`, then updates current workspace and storage.
+- **State**: `switchingToId` (ID being switched to) and derived `switching`; used for loaders and to avoid overwriting with stale results.
+- **Concurrency**: A version ref ensures only the latest switch completes; rejections from `onWorkspaceChange` are caught so they do not surface as unhandled.
+
+## Error Handling
+
+### Error Handler
+
+Centralized error handler (`src/lib/error-handler.ts`):
+
+- Logs errors in development
+- Supports custom error callbacks
+- Provides error context (component, action, metadata)
+- Creates standardized SDKError instances
+
+### Error Boundaries
+
+React Error Boundaries catch component errors:
+
+- `SDKErrorBoundary`: Catches errors in SDK components
+- Prevents app crashes
+- Provides fallback UI
+- Logs errors automatically
+
+**Design Decision**: Multiple error handling layers:
+
+- Network errors: Handled in API utilities
+- Component errors: Handled by Error Boundaries
+- Application errors: Handled by error handler
+- User-facing errors: Can be customized via callbacks
+
+## Performance Optimizations
+
+### Memoization
+
+- Context values memoized to prevent unnecessary re-renders
+- Hook return values memoized
+- API client instances memoized (recreated only when config changes)
+
+### Request Deduplication
+
+- Refs used to prevent duplicate concurrent requests
+- Example: `fetchingProfileRef` in auth provider
+
+### AbortController
+
+- All API calls support AbortSignal
+- Requests cancelled on unmount
+- Prevents memory leaks and race conditions
+
+**Design Decision**: AbortController pattern:
+
+- Prevents race conditions
+- Reduces unnecessary network traffic
+- Better user experience (no stale data)
+
+## Type Safety
+
+### TypeScript Usage
+
+- Full TypeScript coverage
+- Strict type checking
+- Exported types for all public APIs
+
+### Type Exports
+
+All public types exported from `src/index.ts`:
+
+- API types (subscriptions, invoices, plans, pricing variants, quotas, etc.)
+- Plan/subscription: `IPlanVersion`, `IPricingVariant`, `IQuotaByInterval`, `IQuotaIntervalValue`, `IStripePricesByInterval`, `IQuotaOveragesByInterval`, `IPublicPlanVersion`, `IPublicPlansResponse`, and related
+- Currency/quota helpers: `QuotaDisplayValue`, `FormatQuotaWithPriceOptions`, `PlanVersionWithPricingVariants`, `QuotaDisplayWithOverage`
+- Context types
+- Error types
+- Component prop types
+
+**Design Decision**: Comprehensive type exports:
+
+- Better developer experience
+- Type-safe SDK usage
+- IDE autocomplete support
+
+## Event System
+
+### Event Emitter
+
+The SDK includes an event emitter for workspace/user events:
+
+- `workspace:created`
+- `workspace:updated`
+- `workspace:deleted`
+- `workspace:changed`
+- `user:created`
+- `user:updated`
+- etc.
+
+**Design Decision**: Event system:
+
+- Allows consumers to react to SDK events
+- Decouples SDK from consumer app logic
+- Supports custom event handlers via callbacks
+
+## Testing Considerations
+
+### Testability
+
+- Hooks can be tested with `@testing-library/react-hooks`
+- Contexts can be tested independently
+- API clients can be mocked
+- Components can be tested with React Testing Library
+
+### Mocking
+
+- API calls can be mocked at the fetch level
+- Contexts can be mocked with custom providers
+- Event emitter can be mocked
+
+## Bundle Size
+
+### Tree Shaking
+
+- Named exports for all public APIs
+- No default exports (except ErrorBoundary)
+- Side-effect-free modules where possible
+
+### Dependencies
+
+- Minimal external dependencies
+- Peer dependencies for React (not bundled)
+- Radix UI components (tree-shakeable)
+
+## Future Considerations
+
+- **Request Caching**: Optional cache for GET requests
+- **Request Interceptors**: Optional request/response interceptors
+- **Offline Support**: Optional response caching
+- **Migration**: Backward compatible API; deprecation warnings before breaking changes; semantic versioning
+
+## Summary
+
+The BuildBase SDK follows a layered architecture:
+
+1. **Providers**: Nested React providers for feature enablement
+2. **Contexts**: Multiple React contexts for state management
+3. **APIs**: Centralized API clients with shared utilities
+4. **Hooks**: React hooks for consuming SDK features
+5. **Components**: Conditional rendering components
+
+Key design principles:
+
+- **Simplicity**: Easy to use, minimal setup
+- **Type Safety**: Full TypeScript coverage
+- **Performance**: Memoization, request deduplication, AbortController
+- **Error Handling**: Multiple layers of error handling
+- **Developer Experience**: Comprehensive documentation, JSDoc comments, examples

package/docs/ERROR_CODES.md

@@ -0,0 +1,96 @@
+# Error Codes Reference
+
+This document lists error codes used in the BuildBase SDK and their meanings. These codes can be used with `createSDKError()` and may be set on `SDKError.code` when the SDK throws. Not every code is used in every release; this doc serves as the canonical reference.
+
+## SDK Error Codes
+
+### Authentication Errors
+
+| Code              | Description             | When It Occurs                                                          |
+| ----------------- | ----------------------- | ----------------------------------------------------------------------- |
+| `AUTH_FAILED`     | Authentication failed   | When OAuth flow fails or user cannot be authenticated                   |
+| `AUTH_REQUIRED`   | Authentication required | When an operation requires authentication but user is not authenticated |
+| `SESSION_EXPIRED` | Session expired         | When user session has expired and needs to be refreshed                 |
+| `INVALID_SESSION` | Invalid session         | When session data is corrupted or invalid                               |
+
+### Network Errors
+
+| Code              | Description               | When It Occurs                                              |
+| ----------------- | ------------------------- | ----------------------------------------------------------- |
+| `NETWORK_ERROR`   | Network connection failed | When fetch fails due to network issues (offline, DNS, CORS) |
+| `REQUEST_TIMEOUT` | Request timeout           | When request exceeds timeout duration                       |
+| `ABORT_ERROR`     | Request aborted           | When request is cancelled via AbortController               |
+
+### API Errors
+
+| Code           | Description         | When It Occurs                             |
+| -------------- | ------------------- | ------------------------------------------ |
+| `API_ERROR`    | Generic API error   | When API returns an error response         |
+| `BAD_REQUEST`  | Bad request (400)   | When request is malformed or invalid       |
+| `UNAUTHORIZED` | Unauthorized (401)  | When authentication is required or invalid |
+| `FORBIDDEN`    | Forbidden (403)     | When user doesn't have permission          |
+| `NOT_FOUND`    | Not found (404)     | When resource doesn't exist                |
+| `SERVER_ERROR` | Server error (500+) | When server encounters an error            |
+
+### Workspace Errors
+
+| Code                       | Description              | When It Occurs                                           |
+| -------------------------- | ------------------------ | -------------------------------------------------------- |
+| `WORKSPACE_NOT_FOUND`      | Workspace not found      | When workspace doesn't exist or user doesn't have access |
+| `WORKSPACE_ACCESS_DENIED`  | Workspace access denied  | When user doesn't have permission to access workspace    |
+| `WORKSPACE_OWNER_REQUIRED` | Workspace owner required | When operation requires workspace owner (e.g., delete)   |
+| `INVALID_WORKSPACE_ID`     | Invalid workspace ID     | When workspace ID format is invalid                      |
+
+### User Management Errors
+
+| Code                       | Description              | When It Occurs                               |
+| -------------------------- | ------------------------ | -------------------------------------------- |
+| `USER_NOT_FOUND`           | User not found           | When user doesn't exist                      |
+| `USER_ALREADY_EXISTS`      | User already exists      | When trying to add user that already exists  |
+| `CANNOT_REMOVE_OWNER`      | Cannot remove owner      | When trying to remove workspace owner        |
+| `CANNOT_CHANGE_OWNER_ROLE` | Cannot change owner role | When trying to change workspace owner's role |
+
+### Subscription Errors
+
+| Code                     | Description            | When It Occurs                       |
+| ------------------------ | ---------------------- | ------------------------------------ |
+| `SUBSCRIPTION_NOT_FOUND` | Subscription not found | When workspace has no subscription   |
+| `SUBSCRIPTION_ERROR`     | Subscription error     | When subscription operation fails    |
+| `CHECKOUT_ERROR`         | Checkout error         | When checkout session creation fails |
+| `PLAN_NOT_FOUND`         | Plan not found         | When plan doesn't exist              |
+
+### Configuration Errors
+
+| Code                 | Description             | When It Occurs                             |
+| -------------------- | ----------------------- | ------------------------------------------ |
+| `INVALID_CONFIG`     | Invalid configuration   | When SDK configuration is invalid          |
+| `INVALID_SERVER_URL` | Invalid server URL      | When serverUrl is not a valid URL          |
+| `INVALID_ORG_ID`     | Invalid organization ID | When orgId is not a valid MongoDB ObjectId |
+| `INVALID_VERSION`    | Invalid API version     | When API version is not supported          |
+
+### Generic Errors
+
+| Code               | Description      | When It Occurs                       |
+| ------------------ | ---------------- | ------------------------------------ |
+| `UNKNOWN_ERROR`    | Unknown error    | When error type cannot be determined |
+| `VALIDATION_ERROR` | Validation error | When input validation fails          |
+
+## HTTP Status Code Mappings
+
+The SDK automatically maps HTTP status codes to error messages:
+
+| Status Code | Error Message                            |
+| ----------- | ---------------------------------------- |
+| 400         | Bad Request                              |
+| 401         | Unauthorized - Please check your session |
+| 403         | Forbidden - You do not have permission   |
+| 404         | Resource not found                       |
+| 500         | Internal server error                    |
+| 502         | Bad Gateway                              |
+| 503         | Service unavailable                      |
+
+## Error Handling
+
+- **Hook errors**: Use the `error` property from hooks (e.g. `useSaaSWorkspaces()`, `useUserAttributes()`) and show user feedback (toast, inline message).
+- **Async operations**: In `catch` blocks, check `error.message`; for aborted requests, ignore or treat as cancelled.
+- **React errors**: Wrap your app with an error boundary to catch render-time errors.