@buildbase/sdk 0.0.1

package/README.md

@@ -0,0 +1,304 @@
+# @buildbase/sdk
+
+A React SDK for [BuildBase](https://www.buildbase.app/) that provides essential components to build SaaS applications faster. Skip the plumbing and focus on your core product with built-in authentication, workspace management, and user management.
+
+## 🚀 Features
+
+- **🔐 Authentication System** - Complete auth flow with sign-in/sign-out
+- **🏢 Workspace Management** - Multi-workspace support with switching capabilities
+- **👥 Role-Based Access Control** - User roles and workspace-specific permissions
+- **🎯 Feature Flags** - Workspace-level feature toggles
+
+## 📦 Installation
+
+```bash
+npm install @buildbase/sdk
+```
+
+### Peer Dependencies
+
+This package requires React 19 and React DOM 19:
+
+```bash
+npm install react@^19.0.0 react-dom@^19.0.0
+```
+
+## 🏗️ Quick Start
+
+### 1. Import CSS
+
+First, import the required CSS file in your app:
+
+```tsx
+import '@buildbase/sdk/dist/saas-os.css';
+```
+
+### 2. Create Client Provider
+
+Create a client-side provider component:
+
+```tsx
+'use client';
+
+import { SaaSOSProvider } from '@buildbase/sdk';
+import React from 'react';
+
+export default function SaaSProvider(props: { children: React.ReactNode }) {
+  return (
+    <SaaSOSProvider
+      serverUrl="https://your-api-server.com"
+      version="v1"
+      orgId="your-org-id"
+      auth={{
+        clientId: 'your-client-id',
+        redirectUrl: 'http://localhost:3000',
+        callbacks: {
+          verifyToken: async token => {
+            return new Promise(resolve => {
+              fetch('/api/auth/verify', {
+                method: 'POST',
+                body: JSON.stringify({ token }),
+              })
+                .then(response => response.json())
+                .then((data: { valid: boolean }) => {
+                  resolve(data?.valid ?? false);
+                })
+                .catch(error => {
+                  console.error(error);
+                  resolve(false);
+                });
+            });
+          },
+          handleAuthentication: async token => {
+            return new Promise(resolve => {
+              fetch('/api/auth/token', {
+                method: 'POST',
+                body: JSON.stringify({ token }),
+              })
+                .then(response => response.json())
+                .then((data: { token: string; decoded: { id: string } }) => {
+                  localStorage.setItem('auth_token', data?.token ?? '');
+                  resolve();
+                })
+                .catch(error => {
+                  console.error(error);
+                  resolve();
+                });
+            });
+          },
+        },
+      }}
+    >
+      {props.children}
+    </SaaSOSProvider>
+  );
+}
+```
+
+### 3. Wrap Your App
+
+Use the provider in your app layout:
+
+```tsx
+import SaaSProvider from './components/SaaSProvider';
+
+function App() {
+  return (
+    <SaaSProvider>
+      <YourAppContent />
+    </SaaSProvider>
+  );
+}
+
+export default App;
+```
+
+### 4. Workspace Management
+
+The WorkspaceSwitcher component uses a render prop pattern, giving you full control over the UI:
+
+```tsx
+import React from 'react';
+import { WorkspaceSwitcher } from '@buildbase/sdk';
+
+function WorkspaceExample() {
+  return (
+    <WorkspaceSwitcher
+      trigger={currentWorkspace => {
+        if (!currentWorkspace) {
+          return (
+            <div className="flex items-center gap-2 min-w-40 border rounded-md p-2 hover:bg-muted cursor-pointer">
+              <div className="bg-gray-200 flex aspect-square size-8 items-center justify-center rounded-lg"></div>
+              <div className="grid flex-1 text-left text-sm leading-tight">Choose a workspace</div>
+            </div>
+          );
+        }
+
+        return (
+          <div className="flex items-center gap-2 min-w-40 border rounded-md p-2 hover:bg-muted cursor-pointer">
+            <div className="flex items-center justify-center h-full w-full bg-muted rounded-lg max-h-8 max-w-8">
+              {currentWorkspace?.image && (
+                <img src={currentWorkspace?.image} alt={currentWorkspace?.name} />
+              )}
+            </div>
+            <div className="grid flex-1 text-left text-sm leading-tight">
+              <span className="truncate font-medium">{currentWorkspace?.name}</span>
+            </div>
+          </div>
+        );
+      }}
+      onWorkspaceChange={async workspace => {
+        // Handle workspace change
+        console.log('Workspace changed to:', workspace);
+      }}
+    />
+  );
+}
+```
+
+## 🔐 Authentication
+
+### Authentication Hook
+
+Use the `useSaaSAuth` hook to manage authentication state and actions:
+
+```tsx
+import { useSaaSAuth } from '@buildbase/sdk';
+
+function AuthExample() {
+  const { user, isAuthenticated, signIn, signOut, status } = useSaaSAuth();
+
+  return (
+    <div>
+      {!isAuthenticated ? (
+        <div>
+          <h1>Welcome! Please sign in</h1>
+          <button onClick={signIn} disabled={status === 'loading'}>
+            {status === 'loading' ? 'Signing in...' : 'Sign In'}
+          </button>
+        </div>
+      ) : (
+        <div>
+          <h1>Welcome back, {user?.name}!</h1>
+          <p>Email: {user?.email}</p>
+          <p>Role: {user?.role}</p>
+          <button onClick={signOut}>Sign Out</button>
+        </div>
+      )}
+    </div>
+  );
+}
+```
+
+### Authentication Hook Properties
+
+```tsx
+const {
+  user, // Current user object (null if not authenticated)
+  isAuthenticated, // Boolean: true if user is authenticated
+  signIn, // Function: initiates sign-in flow
+  signOut, // Function: signs out the user
+  status, // String: 'idle' | 'loading' | 'authenticated' | 'error'
+} = useSaaSAuth();
+```
+
+### Authentication Components
+
+For declarative rendering, use the conditional components:
+
+```tsx
+import { WhenAuthenticated, WhenUnauthenticated } from '@buildbase/sdk';
+
+function App() {
+  return (
+    <div>
+      <WhenUnauthenticated>
+        <LoginPage />
+      </WhenUnauthenticated>
+
+      <WhenAuthenticated>
+        <Dashboard />
+      </WhenAuthenticated>
+    </div>
+  );
+}
+```
+
+## 👥 Role-Based Access Control
+
+### Role Components
+
+Control access based on user roles:
+
+```tsx
+import { WhenRoles, WhenWorkspaceRoles } from '@buildbase/sdk';
+
+function AdminPanel() {
+  return (
+    <div>
+      {/* Global user roles */}
+      <WhenRoles roles={['admin', 'super-admin']}>
+        <AdminControls />
+      </WhenRoles>
+
+      {/* Workspace-specific roles */}
+      <WhenWorkspaceRoles roles={['owner', 'admin']}>
+        <WorkspaceSettings />
+      </WhenWorkspaceRoles>
+
+      {/* With fallback content */}
+      <WhenRoles roles={['admin']} fallback={<p>You need admin access to view this content</p>}>
+        <SensitiveData />
+      </WhenRoles>
+    </div>
+  );
+}
+```
+
+## 🎛️ Feature Flags
+
+Control feature visibility based on workspace settings:
+
+```tsx
+import { WhenWorkspaceFeatureEnabled, WhenWorkspaceFeatureDisabled } from '@buildbase/sdk';
+
+function FeatureExample() {
+  return (
+    <div>
+      <WhenWorkspaceFeatureEnabled slug="advanced-analytics">
+        <AdvancedAnalytics />
+      </WhenWorkspaceFeatureEnabled>
+
+      <WhenWorkspaceFeatureDisabled slug="beta-features">
+        <p>Beta features are not enabled for this workspace</p>
+      </WhenWorkspaceFeatureDisabled>
+    </div>
+  );
+}
+```
+
+## 🤝 Contributing
+
+1. Fork the repository
+2. Create your feature branch (`git checkout -b feature/amazing-feature`)
+3. Commit your changes (`git commit -m 'Add some amazing feature'`)
+4. Push to the branch (`git push origin feature/amazing-feature`)
+5. Open a Pull Request
+
+## 📄 License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+## 🆘 Support
+
+- 📧 Email: support@buildbase.app
+- 📖 Documentation: [BuildBase Docs](https://docs.buildbase.app/)
+
+## 🔗 Links
+
+- **Homepage**: [BuildBase](https://www.buildbase.app/)
+- **NPM Package**: [@buildbase/sdk](https://www.npmjs.com/package/@buildbase/sdk)
+
+---
+
+Made with ❤️ by the BuildBase team

package/dist/index.d.ts

@@ -0,0 +1,310 @@
+import * as react from 'react';
+import react__default, { ReactNode } from 'react';
+import * as react_jsx_runtime from 'react/jsx-runtime';
+
+declare enum AuthStatus {
+    loading = "loading",
+    authenticated = "authenticated",
+    unauthenticated = "unauthenticated",
+    authenticating = "authenticating"
+}
+interface AuthUser {
+    id: string;
+    name: string;
+    org: string;
+    email: string;
+    emailVerified: boolean;
+    clientId: string;
+    role: string;
+    image?: string;
+}
+interface AuthSession {
+    user: AuthUser;
+    accessToken: string;
+    expires: string;
+}
+interface IAuthState {
+    user: AuthUser | null;
+    session: AuthSession | null;
+    isLoading: boolean;
+    isAuthenticated: boolean;
+    isRedirecting: boolean;
+    status: AuthStatus;
+}
+interface IAuthConfig {
+    clientId: string;
+    redirectUrl: string;
+    callbacks?: IAuthCallbacks;
+}
+interface IAuthCallbacks {
+    handleAuthentication: (token: string) => Promise<void>;
+    verifyToken: (token: string) => Promise<boolean>;
+}
+
+interface IOsConfig {
+    serverUrl: string;
+    version: string;
+    orgId: string;
+}
+interface IOsState extends IOsConfig {
+    auth?: IAuthConfig;
+}
+
+interface SaaSOSProviderProps extends IOsState {
+    children: react__default.ReactNode;
+}
+declare const SaaSOSProvider: react__default.FC<SaaSOSProviderProps>;
+
+type Language = 'en' | 'es' | 'fr' | 'de' | 'zh' | 'ja' | 'ko';
+interface FormText {
+    nameLabel: string;
+    emailLabel: string;
+    submitText: string;
+    submittingText: string;
+    errorMessage: string;
+}
+interface BetaFormProps {
+    onSuccess?: () => void;
+    onError?: (error: string) => void;
+    className?: string;
+    fieldClassName?: string;
+    language?: Language;
+    customTexts?: Partial<FormText>;
+    autoFocus?: boolean;
+    showSuccessMessage?: boolean;
+    successMessageDuration?: number;
+    hideLogo?: boolean;
+    hideTitles?: boolean;
+}
+declare const BetaForm: react__default.FC<BetaFormProps>;
+
+interface IProps$2 {
+    children: React.ReactNode;
+}
+declare const WhenAuthenticated: (props: IProps$2) => react.ReactNode;
+declare const WhenUnauthenticated: (props: IProps$2) => react.ReactNode;
+
+interface IProps$1 {
+    roles: string[];
+    children: React.ReactNode;
+    fallback?: React.ReactNode;
+}
+declare const WhenRoles: (props: IProps$1) => react.ReactNode;
+declare const WhenWorkspaceRoles: (props: IProps$1) => react.ReactNode;
+
+interface IProps {
+    slug: string;
+    children: React.ReactNode;
+}
+declare const WhenWorkspaceFeatureEnabled: (props: IProps) => react.ReactNode;
+declare const WhenWorkspaceFeatureDisabled: (props: IProps) => react.ReactNode;
+
+declare function useSaaSAuth(): {
+    user: AuthUser | null;
+    session: AuthSession | null;
+    isLoading: boolean;
+    isAuthenticated: boolean;
+    isRedirecting: boolean;
+    status: AuthStatus;
+    signIn: () => Promise<void>;
+    signOut: () => Promise<void>;
+};
+
+interface IDocument {
+    _id: string;
+    id: string;
+    createdAt: string;
+    updatedAt: string;
+    deleted: boolean;
+}
+interface IUser extends IDocument {
+    _id: string;
+    name: string;
+    email: string;
+    image: string;
+    role: string;
+    country: string;
+    timezone: string;
+    language: string;
+    currency: string;
+}
+
+interface IWorkspace {
+    _id: string;
+    name: string;
+    image?: string;
+    workspaceId: string;
+    users: IUser[];
+    roles: string[];
+    createdBy: string | IUser;
+    features: Record<string, boolean>;
+}
+interface IWorkspaceFeature {
+    _id: string;
+    name: string;
+    description: string;
+    userManaged: boolean;
+    defaultValue: boolean;
+    slug: string;
+    category: string;
+    createdAt: Date;
+    updatedAt: Date;
+}
+interface IWorkspaceUser {
+    _id: string;
+    workspace: string | IWorkspace;
+    user: string | IUser;
+    role: string;
+}
+
+declare function WorkspaceSwitcher(props: {
+    trigger: (currentWorkspace: IWorkspace | null) => ReactNode;
+    onWorkspaceChange: (workspace: IWorkspace) => Promise<void>;
+}): react_jsx_runtime.JSX.Element;
+
+declare const useSaaSWorkspaces: () => {
+    workspaces: IWorkspace[];
+    loading: boolean;
+    error: string | null;
+    fetchWorkspaces: () => Promise<void>;
+    refreshWorkspaces: () => Promise<void>;
+    refreshing: boolean;
+    WorkspaceSwitcher: typeof WorkspaceSwitcher;
+    currentWorkspace: IWorkspace | null;
+    setCurrentWorkspace: (ws: IWorkspace) => void;
+    resetCurrentWorkspace: () => void;
+    createWorkspace: (name: string, image: string) => Promise<void>;
+    allFeatures: IWorkspaceFeature[];
+    getFeatures: () => Promise<IWorkspaceFeature[]>;
+    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<IWorkspaceUser>;
+    removeUser: (workspaceId: string, userId: string) => Promise<{
+        success: boolean;
+    }>;
+    updateUser: (workspaceId: string, userId: string, config: Partial<IWorkspaceUser>) => Promise<IWorkspaceUser>;
+    getProfile: () => Promise<IUser>;
+    updateUserProfile: (config: Partial<IUser>) => Promise<IUser>;
+};
+
+type AuthAction = {
+    type: 'AUTHENTICATION_STARTED';
+} | {
+    type: 'AUTHENTICATION_FAILED';
+} | {
+    type: 'SET_SESSION';
+    payload: AuthSession;
+} | {
+    type: 'REMOVE_SESSION';
+};
+type WorkspaceAction = {
+    type: 'SET_WORKSPACES';
+    payload: IWorkspace[];
+} | {
+    type: 'SET_ALL_FEATURES';
+    payload: IWorkspaceFeature[];
+} | {
+    type: 'SET_CURRENT_WORKSPACE';
+    payload: IWorkspace;
+} | {
+    type: 'RESET_CURRENT_WORKSPACE';
+} | {
+    type: 'SET_IS_INITIALIZED';
+    payload: boolean;
+} | {
+    type: 'SET_LOADING';
+    payload: boolean;
+} | {
+    type: 'SET_ERROR';
+    payload: string | null;
+} | {
+    type: 'SET_REFRESHING';
+    payload: boolean;
+} | {
+    type: 'SET_SWITCHING';
+    payload: boolean;
+};
+interface WorkspaceState {
+    workspaces: IWorkspace[];
+    loading: boolean;
+    error: string | null;
+    currentWorkspace: IWorkspace | null;
+    refreshing: boolean;
+    switching: boolean;
+    isInitialized: boolean;
+    allFeatures: IWorkspaceFeature[];
+}
+type OSAction = {
+    type: 'SET_SAAS_OS_CONFIG';
+    payload: IOsState;
+} | {
+    type: 'REMOVE_SAAS_OS_CONFIG';
+};
+
+/**
+ * Combined SDK State
+ * Represents the complete state structure across all contexts
+ */
+interface SDKState {
+    os: IOsState;
+    auth: IAuthState;
+    workspaces: WorkspaceState;
+}
+/**
+ * Combined selector hook - select from all contexts at once
+ *
+ * @param selector Function that selects a value from the combined SDK state
+ * @param equalityFn Optional equality function for comparison (default: Object.is)
+ *
+ * @example
+ * ```tsx
+ * // Get entire combined state
+ * const sdk = useAppSelector();
+ *
+ * // Get specific context
+ * const auth = useAppSelector(state => state.auth);
+ * const user = useAppSelector(state => state.auth.user);
+ *
+ * // Get multiple fields across contexts
+ * const { user, currentWorkspace, serverUrl } = useAppSelector(state => ({
+ *   user: state.auth.user,
+ *   currentWorkspace: state.workspaces.currentWorkspace,
+ *   serverUrl: state.os.serverUrl,
+ * }));
+ * ```
+ */
+declare function useAppSelector<Selected = SDKState>(selector?: (state: SDKState) => Selected, equalityFn?: (a: Selected, b: Selected) => boolean): Selected;
+
+/**
+ * Combined SDK Dispatch
+ * Provides dispatch functions for all contexts
+ */
+interface SDKDispatch {
+    auth: (action: AuthAction) => void;
+    os: (action: OSAction) => void;
+    workspaces: (action: WorkspaceAction) => void;
+}
+/**
+ * Combined dispatch hook - dispatch actions to all contexts
+ *
+ * @example
+ * ```tsx
+ * const dispatch = useAppDispatch();
+ *
+ * // Dispatch to auth context
+ * dispatch.auth(authActions.setSession(session));
+ *
+ * // Dispatch to workspace context
+ * dispatch.workspaces(workspaceActions.setCurrentWorkspace(workspace));
+ *
+ * // Dispatch to OS context
+ * dispatch.os(osActions.setSaaSOSConfig(config));
+ * ```
+ */
+declare function useAppDispatch(): SDKDispatch;
+
+export { BetaForm, SaaSOSProvider, WhenAuthenticated, WhenRoles, WhenUnauthenticated, WhenWorkspaceFeatureDisabled, WhenWorkspaceFeatureEnabled, WhenWorkspaceRoles, WorkspaceSwitcher, useAppDispatch, useAppSelector, useSaaSAuth, useSaaSWorkspaces };
+export type { SDKDispatch, SDKState, SaaSOSProviderProps };