@buildbase/sdk 0.0.24 → 0.0.25

package/dist/types/lib/api-base.d.ts

@@ -1,49 +0,0 @@
-/**
- * Base API client for SDK endpoints.
- * All domain API classes (WorkspaceApi, UserApi, etc.) extend this to share
- * URL building, auth headers, and request/response handling.
- */
-import type { ApiVersion } from '../providers/os/types';
-export interface IBaseApiConfig {
-    serverUrl: string;
-    version: ApiVersion;
-    orgId?: string;
-    /** When true, ensureReady() also requires orgId. Used by WorkspaceApi and SettingsApi. */
-    requireOrgId?: boolean;
-    /** API path segment after version (default 'public'). e.g. 'public' => .../v1/public, 'beta' => .../v1/beta */
-    basePath?: string;
-}
-/**
- * Base class for SDK API clients.
- * Provides:
- * - baseUrl: `${serverUrl}/api/${version}/public`
- * - getAuthHeaders()
- * - fetchJson<T>(path, init, errorMessage): GET/POST/etc. with handleApiResponse
- * - fetchResponse(path, init): raw Response for custom parsing (e.g. non-JSON or custom error handling)
- */
-export declare abstract class BaseApi {
-    protected readonly serverUrl: string;
-    protected readonly version: ApiVersion;
-    protected readonly orgId: string | undefined;
-    private readonly requireOrgId;
-    private readonly basePath;
-    constructor(config: IBaseApiConfig);
-    /** Throws if config is not ready for API calls. Called automatically by fetchJson/fetchResponse. */
-    protected ensureReady(): void;
-    /** Base URL: ${serverUrl}/api/${version}/${basePath} */
-    protected get baseUrl(): string;
-    /** Auth headers (x-session-id). Subclasses can override to add more. */
-    protected getAuthHeaders(): Record<string, string>;
-    /** Build full URL from path (path can be "workspaces" or "/workspaces"). */
-    protected url(path: string): string;
-    /**
-     * Execute request and parse JSON with handleApiResponse (throws on !response.ok).
-     * Use for standard JSON APIs.
-     */
-    protected fetchJson<T>(path: string, init?: RequestInit, errorMessage?: string): Promise<T>;
-    /**
-     * Execute request and return raw Response (for custom parsing or error handling).
-     * Caller is responsible for checking response.ok and parsing body.
-     */
-    protected fetchResponse(path: string, init?: RequestInit): Promise<Response>;
-}

package/dist/types/lib/api-client.d.ts

@@ -1,25 +0,0 @@
-import { AxiosRequestConfig } from 'axios';
-export interface ApiClientConfig {
-    baseURL?: string;
-    timeout?: number;
-    headers?: Record<string, string>;
-}
-export interface ApiResponse<T = unknown> {
-    data: T;
-    status: number;
-    statusText: string;
-    headers: Record<string, string | string[]> | Record<string, unknown>;
-}
-export declare class ApiClient {
-    private client;
-    constructor(config?: ApiClientConfig);
-    get<T = unknown>(url: string, config?: AxiosRequestConfig): Promise<ApiResponse<T>>;
-    post<T = unknown>(url: string, data?: unknown, config?: AxiosRequestConfig): Promise<ApiResponse<T>>;
-    put<T = unknown>(url: string, data?: unknown, config?: AxiosRequestConfig): Promise<ApiResponse<T>>;
-    delete<T = unknown>(url: string, config?: AxiosRequestConfig): Promise<ApiResponse<T>>;
-    patch<T = unknown>(url: string, data?: unknown, config?: AxiosRequestConfig): Promise<ApiResponse<T>>;
-    setBaseURL(baseURL: string): void;
-    setHeader(key: string, value: string): void;
-    removeHeader(key: string): void;
-}
-export declare const defaultApiClient: ApiClient;

package/dist/types/lib/api-utils.d.ts

@@ -1,182 +0,0 @@
-/**
- * API utility functions for consistent error handling and request management
- */
-/**
- * Check if an error is from AbortController (request was cancelled).
- * Useful for ignoring abort errors when components unmount or requests are cancelled.
- *
- * @param error - The error to check
- * @returns True if the error is an AbortError, false otherwise
- *
- * @example
- * ```tsx
- * try {
- *   await safeFetch(url, { signal });
- * } catch (error) {
- *   if (isAbortError(error)) {
- *     // Request was cancelled, ignore
- *     return;
- *   }
- *   // Handle other errors
- *   console.error('Request failed:', error);
- * }
- * ```
- */
-export declare function isAbortError(error: unknown): boolean;
-/**
- * Safely execute a fetch request with network error handling.
- * Wraps native fetch to provide better error messages for network failures.
- * Supports AbortSignal - when aborted, throws with name 'AbortError' (caller can use isAbortError()).
- * In development mode, automatically logs request/response for debugging (prefixed with [SDK API]).
- * Sensitive data (tokens, passwords) is automatically redacted from logs.
- *
- * @param url - The URL to fetch
- * @param options - Optional fetch options (RequestInit), including AbortSignal
- * @returns Promise resolving to Response object
- * @throws {Error} Network errors with descriptive messages, or AbortError if request was aborted
- *
- * @example
- * ```tsx
- * // Basic usage
- * const response = await safeFetch('/api/users');
- * ```
- *
- * @example
- * ```tsx
- * // With abort signal
- * const controller = new AbortController();
- * const response = await safeFetch('/api/users', {
- *   signal: controller.signal,
- *   method: 'POST',
- *   body: JSON.stringify({ name: 'John' }),
- * });
- *
- * // Cancel request
- * controller.abort();
- * ```
- *
- * @example
- * ```tsx
- * // Handle network errors
- * try {
- *   const response = await safeFetch('/api/users');
- * } catch (error) {
- *   if (isAbortError(error)) {
- *     // Request was cancelled
- *     return;
- *   }
- *   // Network error: "Network error: Please check your internet connection"
- *   console.error(error.message);
- * }
- * ```
- */
-export declare function safeFetch(url: string, options?: RequestInit): Promise<Response>;
-/**
- * Extract error message from a failed response.
- * Parses JSON body and returns message/error field, or defaultMsg if not available.
- *
- * @param response - The Response object (typically from a failed request)
- * @param defaultMsg - Default message if parsing fails or no message in body
- * @returns Promise resolving to the error message string
- *
- * @example
- * ```tsx
- * const response = await safeFetch('/api/users');
- * if (!response.ok) {
- *   const msg = await getErrorMessage(response, 'Failed to fetch users');
- *   throw new Error(msg);
- * }
- * ```
- */
-export declare function getErrorMessage(response: Response, defaultMsg: string): Promise<string>;
-/**
- * Parse JSON response with error handling.
- * Provides better error messages if response is not valid JSON.
- *
- * @param response - The Response object to parse
- * @returns Promise resolving to parsed JSON data
- * @throws {Error} If response body is empty or not valid JSON
- *
- * @example
- * ```tsx
- * const response = await safeFetch('/api/users');
- * const users = await parseJsonResponse<User[]>(response);
- * ```
- */
-export declare function parseJsonResponse<T>(response: Response): Promise<T>;
-/**
- * Create a standardized API error from a response.
- * Provides user-friendly error messages based on HTTP status codes.
- *
- * @param response - The Response object with error status
- * @param defaultMessage - Default error message if status-specific message not available
- * @returns Error instance with descriptive message
- *
- * @example
- * ```tsx
- * const response = await safeFetch('/api/users');
- * if (!response.ok) {
- *   throw createApiError(response, 'Failed to fetch users');
- *   // Error message: "Failed to fetch users (401: Unauthorized - Please check your session)"
- * }
- * ```
- */
-export declare function createApiError(response: Response, defaultMessage: string): Error;
-/**
- * Handle API response with consistent error handling.
- * Checks response status, parses JSON, and provides standardized error messages.
- * This is the recommended way to handle API responses in the SDK.
- *
- * @param response - The Response object to handle
- * @param defaultErrorMessage - Default error message if response is not ok
- * @returns Promise resolving to parsed JSON data
- * @throws {Error} If response is not ok or JSON parsing fails
- *
- * @example
- * ```tsx
- * const response = await safeFetch('/api/users');
- * const users = await handleApiResponse<User[]>(response, 'Failed to fetch users');
- * ```
- *
- * @example
- * ```tsx
- * // With error handling
- * try {
- *   const response = await safeFetch('/api/users');
- *   const users = await handleApiResponse<User[]>(response);
- * } catch (error) {
- *   // Error message includes status code and descriptive text
- *   console.error(error.message);
- * }
- * ```
- */
-export declare function handleApiResponse<T>(response: Response, defaultErrorMessage?: string): Promise<T>;
-/**
- * Fetch with timeout support.
- * Automatically cancels request if it takes longer than specified timeout.
- *
- * @param url - The URL to fetch
- * @param options - Optional fetch options (RequestInit)
- * @param timeout - Timeout in milliseconds (default: 10000ms / 10 seconds)
- * @returns Promise resolving to Response object
- * @throws {Error} If request times out: "Request timeout after {timeout}ms"
- *
- * @example
- * ```tsx
- * // 5 second timeout
- * const response = await fetchWithTimeout('/api/users', {}, 5000);
- * ```
- *
- * @example
- * ```tsx
- * // Handle timeout
- * try {
- *   const response = await fetchWithTimeout('/api/users', {}, 5000);
- * } catch (error) {
- *   if (error.message.includes('timeout')) {
- *     console.error('Request took too long');
- *   }
- * }
- * ```
- */
-export declare function fetchWithTimeout(url: string, options?: RequestInit, timeout?: number): Promise<Response>;

package/dist/types/lib/error-handler.d.ts

@@ -1,118 +0,0 @@
-/**
- * Centralized Error Handler for SDK
- * Provides consistent error handling, logging, and user-facing error management
- */
-export interface SDKErrorContext {
-    component?: string;
-    action?: string;
-    metadata?: Record<string, unknown>;
-}
-export 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);
-}
-export 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;
-}
-export 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' },
- *   });
- * }
- * ```
- */
-export declare function handleError(error: Error | unknown, context?: SDKErrorContext): void;
-/**
- * Handle an error only if it is not an AbortError.
- * Convenience for async code that uses AbortSignal - call this in catch and abort errors are ignored.
- *
- * @param error - The error that occurred
- * @param context - Optional context about where the error occurred
- * @returns true if error was handled, false if it was an abort error (ignored)
- *
- * @example
- * ```tsx
- * try {
- *   await safeFetch(url, { signal });
- * } catch (error) {
- *   handleErrorUnlessAborted(error, { component: 'MyComponent', action: 'fetch' });
- * }
- * ```
- */
-export declare function handleErrorUnlessAborted(error: Error | unknown, context?: SDKErrorContext): boolean;
-/**
- * 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
- * );
- * ```
- */
-export declare function createSDKError(message: string, code?: string, context?: SDKErrorContext, originalError?: Error): SDKError;
-export {};

package/dist/types/lib/logger.d.ts

@@ -1,27 +0,0 @@
-/**
- * Centralized logger for SDK
- * All console output should go through this for consistency and configurable behavior
- */
-/**
- * Configure the SDK logger
- */
-export declare function configureLogger(config: {
-    enableLogging?: boolean;
-}): void;
-/**
- * Log info (dev only, respects enableLogging)
- */
-export declare function sdkLog(message: string, ...args: unknown[]): void;
-/**
- * Log warning (dev only, respects enableLogging)
- */
-export declare function sdkWarn(message: string, ...args: unknown[]): void;
-/**
- * Log error (dev only, respects enableLogging)
- */
-export declare function sdkLogError(message: string, ...args: unknown[]): void;
-/**
- * Log internal/critical error - always logs.
- * Use when the error handling system itself fails (e.g. user's onError callback throws).
- */
-export declare function sdkError(message: string, ...args: unknown[]): void;

package/dist/types/lib/useAsyncEffect.d.ts

@@ -1,29 +0,0 @@
-import type { DependencyList } from 'react';
-export interface UseAsyncEffectOptions {
-    /**
-     * Called when the effect promise rejects (except for AbortError which is ignored).
-     */
-    onError?: (err: unknown) => void;
-}
-/**
- * Encapsulates the AbortController + async effect pattern.
- * Provides cancellation on cleanup and optional error handling.
- *
- * @param effect - Async function that receives AbortSignal for cancellation
- * @param deps - Dependency array (same as useEffect)
- * @param options - Optional onError callback for unhandled rejections
- *
- * @example
- * ```tsx
- * useAsyncEffect(
- *   async (signal) => {
- *     const response = await safeFetch(url, { signal });
- *     const data = await response.json();
- *     setData(data);
- *   },
- *   [url],
- *   { onError: (err) => handleError(err, { component: 'MyComponent', action: 'fetch' }) }
- * );
- * ```
- */
-export declare function useAsyncEffect(effect: (signal: AbortSignal) => Promise<void>, deps: DependencyList, options?: UseAsyncEffectOptions): void;

package/dist/types/lib/utils.d.ts

@@ -1,7 +0,0 @@
-import { type ClassValue } from 'clsx';
-/**
- * Check if running in development mode.
- * Safe for browser bundles where process may be undefined.
- */
-export declare function isDevelopment(): boolean;
-export declare function cn(...inputs: ClassValue[]): string;

package/dist/types/providers/ContextConfigProvider.d.ts

@@ -1,15 +0,0 @@
-import React from 'react';
-import type { IAuthConfig } from './auth/types';
-import { type IOsState } from './os/types';
-interface ContextConfigProviderProps {
-    config: IOsState;
-    auth?: IAuthConfig;
-    children: React.ReactNode;
-}
-/**
- * Context Config Provider
- * Initializes OS configuration in Context API mode
- * Similar to SaaSConfigProvider but for Context API
- */
-export declare const ContextConfigProvider: React.FC<ContextConfigProviderProps>;
-export {};

package/dist/types/providers/PortalContainer.d.ts

@@ -1,9 +0,0 @@
-import React from 'react';
-export declare const PortalContext: React.Context<{
-    container: HTMLDivElement | null;
-    setContainer: (container: HTMLDivElement | null) => void;
-}>;
-declare const PortalProvider: React.MemoExoticComponent<({ children }: {
-    children: React.ReactNode;
-}) => import("react/jsx-runtime").JSX.Element>;
-export default PortalProvider;

package/dist/types/providers/SaaSOSProvider.d.ts

@@ -1,7 +0,0 @@
-import React from 'react';
-import '../styles/globals.css';
-import { IOsState } from './os/types';
-export interface SaaSOSProviderProps extends IOsState {
-    children: React.ReactNode;
-}
-export declare const SaaSOSProvider: React.FC<SaaSOSProviderProps>;

package/dist/types/providers/auth/api.d.ts

@@ -1,12 +0,0 @@
-/**
- * Centralized API client for auth (profile).
- * Extends BaseApi; uses explicit sessionId for profile (e.g. after redirect or hydration).
- */
-import { IUser } from '../../api/types';
-import { BaseApi } from '../../lib/api-base';
-import type { IOsConfig } from '../os/types';
-export declare class AuthApi extends BaseApi {
-    constructor(config: Pick<IOsConfig, 'serverUrl' | 'version'>);
-    /** Fetch user profile with the given session ID (used after OAuth redirect or from storage). */
-    getProfile(sessionId: string, signal?: AbortSignal): Promise<IUser>;
-}

package/dist/types/providers/auth/hooks.d.ts

@@ -1,75 +0,0 @@
-import { WorkspaceSettingsSection } from '../workspace/ui/SettingsDialog';
-/**
- * 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>
- *   );
- * }
- * ```
- */
-/** Internal: select auth slice. Used by AuthProviderWrapper and useSaaSAuth. */
-export declare function useAuthState(): import("./types").IAuthState;
-export declare function useSaaSAuth(): {
-    signIn: () => Promise<void>;
-    signOut: () => Promise<void>;
-    openWorkspaceSettings: (section?: WorkspaceSettingsSection) => void;
-    isAuthenticated: boolean;
-    isLoading: boolean;
-    isRedirecting: boolean;
-    user: import("./types").AuthUser | undefined;
-    session: import("./types").AuthSession | null;
-    status: import("./types").AuthStatus;
-};

package/dist/types/providers/auth/provider.d.ts

@@ -1,13 +0,0 @@
-import React, { ReactNode } from 'react';
-import { IAuthCallbacks } from './types';
-interface IProps {
-    children: ReactNode;
-    callbacks?: IAuthCallbacks;
-}
-/**
- * AuthProvider wrapper that adds authentication logic
- * This wraps the AuthContextProvider and adds token handling, callbacks, etc.
- */
-export declare const AuthProviderWrapper: React.MemoExoticComponent<({ children, callbacks }: IProps) => import("react/jsx-runtime").JSX.Element>;
-export declare const AuthProvider: React.MemoExoticComponent<({ children, callbacks }: IProps) => import("react/jsx-runtime").JSX.Element>;
-export {};

package/dist/types/providers/auth/types.d.ts

@@ -1,62 +0,0 @@
-import type { EventData, EventType } from '../events/types';
-import type { IWorkspace } from '../workspace/types';
-export declare enum AuthStatus {
-    loading = "loading",
-    redirecting = "redirecting",
-    authenticated = "authenticated",
-    unauthenticated = "unauthenticated",
-    authenticating = "authenticating"
-}
-/** Derive booleans from status (single source of truth) */
-export declare function getAuthFlags(status: AuthStatus): {
-    isAuthenticated: boolean;
-    isLoading: boolean;
-    isRedirecting: boolean;
-};
-export interface AuthUser {
-    id: string;
-    name: string;
-    org: string;
-    email: string;
-    emailVerified: boolean;
-    clientId: string;
-    role: string;
-    image?: string;
-}
-export interface AuthSession {
-    user: AuthUser;
-    sessionId: string;
-    expires: string;
-}
-export interface IAuthState {
-    session: AuthSession | null;
-    status: AuthStatus;
-}
-export interface IAuthConfig {
-    clientId: string;
-    redirectUrl: string;
-    callbacks?: IAuthCallbacks;
-}
-export interface IAuthCallbacks {
-    handleAuthentication: (code: string) => Promise<{
-        sessionId: string;
-    }>;
-    onSignOut: () => Promise<void>;
-    /**
-     * Event handler for User and Workspace events
-     * @param eventType - The type of event that occurred
-     * @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>;
-}
-export interface OnWorkspaceChangeParams {
-    workspace: IWorkspace;
-    user: AuthUser | null;
-    role: string | null;
-}

package/dist/types/providers/auth/utils.d.ts

@@ -1,40 +0,0 @@
-import { IUser } from '../../api/types';
-import type { AuthSession, AuthUser } from './types';
-/**
- * Map IUser from API to AuthUser for session
- * @throws Error if user data is missing required ID or email fields
- */
-export declare function mapIUserToAuthUser(userData: IUser, orgId: string, clientId: string): AuthUser;
-/**
- * Centralized Session Management
- * Only stores sessionId in localStorage - user data is kept in context only
- * This ensures we always fetch fresh user data on page refresh
- */
-/**
- * Save sessionId to localStorage
- * Note: Only sessionId is stored, user data is kept in context state only
- * @param sessionId - The sessionId string to save
- */
-export declare function setSessionId(sessionId: string): void;
-/**
- * Remove sessionId from localStorage
- */
-export declare function removeSession(): void;
-/**
- * Get sessionId from localStorage
- * @returns The sessionId string or null if not found
- */
-export declare function getSessionId(): string | null;
-/**
- * Get sessionId (alias for getSessionId for backward compatibility)
- * @returns The sessionId string or null if not found
- */
-export declare function getAccessToken(): string | null;
-/**
- * Get authentication headers with x-session-id
- * Centralized function for all API requests
- */
-export declare function getAuthHeaders(): Record<string, string>;
-export declare function getTokenFromUrl(): string | null;
-export declare function removeTokenFromUrl(): void;
-export declare function createSession(user: AuthUser, sessionId: string): AuthSession;