@buildbase/sdk 0.0.54 → 0.0.55

package/dist/react/index.d.ts

@@ -1012,7 +1012,7 @@ interface ISettings {
         /** Auto-create workspace on first login */
         autoCreateFirst: boolean;
     };
-    [key: string]: any;
+    [key: string]: unknown;
 }
 
 /**
@@ -1026,9 +1026,14 @@ interface IOsConfig {
     version: ApiVersion;
     orgId: string;
 }
+/** Lifecycle of the one-time org-settings fetch. */
+type SettingsStatus = 'idle' | 'loading' | 'loaded' | 'error';
 interface IOsState extends IOsConfig {
     auth?: IAuthConfig;
     settings?: ISettings | null;
+    /** State of the settings fetch — lets UI wait instead of guessing with `?? true` defaults. */
+    settingsStatus?: SettingsStatus;
+    settingsError?: string | null;
 }
 
 /**
@@ -1091,6 +1096,7 @@ interface IBaseApiConfig {
  * - 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)
+ * - fetchUnwrapped<T>(path, init, errorMessage): fetch → throw on !ok → unwrap { success, data } envelope
  */
 declare abstract class BaseApi {
     protected readonly serverUrl: string;
@@ -1139,6 +1145,12 @@ declare abstract class BaseApi {
      * Caller is responsible for checking response.ok and parsing body.
      */
     protected fetchResponse(path: string, init?: RequestInit): Promise<Response>;
+    /**
+     * Execute request, throw a parsed error on !response.ok, and unwrap the
+     * `{ success, data }` envelope. Shorthand for the common
+     * fetchResponse → throwResponseError → unwrapResponse sequence.
+     */
+    protected fetchUnwrapped<T>(path: string, init?: RequestInit, errorMessage?: string): Promise<T>;
     /**
      * Execute request against an absolute URL (bypasses baseUrl).
      * Useful for endpoints outside the default basePath (e.g. /auth vs /public).
@@ -1180,21 +1192,26 @@ interface AuthRequestParams {
     };
     state?: string;
 }
+/**
+ * Unwrapped payload of a successful auth request.
+ * ⚠️ Prior to the envelope unification this type described the raw
+ * `{ success, data, message }` wire envelope; `requestAuth` now unwraps the
+ * envelope like every other SDK method and resolves with the payload only.
+ */
 interface AuthRequestResponse {
-    success: boolean;
-    data: {
-        redirectUrl: string;
-    };
-    message: string;
+    redirectUrl: string;
 }
 declare class AuthApi extends BaseApi {
     constructor(config: Pick<IOsConfig, 'serverUrl' | 'version'> & {
         sessionId?: string;
     });
     /**
-     * Initiate OAuth sign-in flow. Returns redirect URL to the auth provider.
+     * Initiate OAuth sign-in flow. Resolves with the redirect URL to the auth provider.
      * Auth endpoints sit at /api/v1/auth/ (outside the /public basePath),
-     * so we use fetchAbsoluteUrl to get timeout, retry, and error handling via BaseApi.
+     * so we use fetchAbsoluteUrl to get timeout, retry, and error handling via
+     * BaseApi, then apply the standard throwResponseError → unwrapResponse
+     * sequence (the fetchUnwrapped convention). Non-2xx responses and 2xx
+     * envelopes with `success: false` both throw a structured Error.
      */
     requestAuth(params: AuthRequestParams): Promise<AuthRequestResponse>;
     /** Fetch user profile with the given session ID (used after OAuth redirect or from storage). */
@@ -1345,7 +1362,7 @@ interface NotificationData {
         push?: boolean;
     };
     /** Any additional merge tags available as {{key}} in the email template. */
-    [key: string]: any;
+    [key: string]: unknown;
 }
 /** Result of sending a notification. */
 interface NotificationResult {
@@ -1376,64 +1393,64 @@ declare class WorkspaceApi extends BaseApi {
         sessionId?: string;
         onUnauthorized?: () => void;
     });
-    getWorkspaces(): Promise<IWorkspace[]>;
+    getWorkspaces(signal?: AbortSignal): Promise<IWorkspace[]>;
     createWorkspace(data: {
         name: string;
         image?: string;
-    }): Promise<IWorkspace>;
-    updateWorkspace(id: string, data: Partial<IWorkspace>): Promise<IWorkspace>;
-    deleteWorkspace(id: string): Promise<{
+    }, signal?: AbortSignal): Promise<IWorkspace>;
+    updateWorkspace(id: string, data: Partial<IWorkspace>, signal?: AbortSignal): Promise<IWorkspace>;
+    deleteWorkspace(id: string, signal?: AbortSignal): Promise<{
         success: boolean;
     }>;
-    getWorkspaceUsers(workspaceId: string): Promise<IWorkspaceUser[]>;
+    getWorkspaceUsers(workspaceId: string, signal?: AbortSignal): Promise<IWorkspaceUser[]>;
     addUser(workspaceId: string, config: {
         email: string;
         role: string;
-    }): Promise<{
+    }, signal?: AbortSignal): Promise<{
         userId: string;
         workspace: IWorkspace;
         message: string;
     }>;
-    removeUser(workspaceId: string, userId: string): Promise<{
+    removeUser(workspaceId: string, userId: string, signal?: AbortSignal): Promise<{
         userId: string;
         workspace: IWorkspace;
         message: string;
     }>;
-    updateUser(workspaceId: string, userId: string, data: Partial<IWorkspaceUser>): Promise<{
+    updateUser(workspaceId: string, userId: string, data: Partial<IWorkspaceUser>, signal?: AbortSignal): Promise<{
         userId: string;
         workspace: IWorkspace;
         message: string;
     }>;
     updateSettings(data: {
         permissions: Record<string, string[]>;
-    }): Promise<any>;
-    updateWorkspacePermissions(workspaceId: string, permissions: Record<string, string[]>): Promise<any>;
-    getFeatures(): Promise<IWorkspaceFeature[]>;
-    updateFeature(workspaceId: string, key: string, value: boolean): Promise<IWorkspace>;
-    getWorkspace(workspaceId: string): Promise<IWorkspace>;
-    getProfile(): Promise<IUser>;
-    updateUserProfile(config: Partial<IUser>): Promise<IUser>;
-    getPasskeys(): Promise<IPasskeySummary[]>;
-    renamePasskey(passkeyId: string, name: string): Promise<void>;
-    deletePasskey(passkeyId: string): Promise<void>;
+    }, signal?: AbortSignal): Promise<any>;
+    updateWorkspacePermissions(workspaceId: string, permissions: Record<string, string[]>, signal?: AbortSignal): Promise<any>;
+    getFeatures(signal?: AbortSignal): Promise<IWorkspaceFeature[]>;
+    updateFeature(workspaceId: string, key: string, value: boolean, signal?: AbortSignal): Promise<IWorkspace>;
+    getWorkspace(workspaceId: string, signal?: AbortSignal): Promise<IWorkspace>;
+    getProfile(signal?: AbortSignal): Promise<IUser>;
+    updateUserProfile(config: Partial<IUser>, signal?: AbortSignal): Promise<IUser>;
+    getPasskeys(signal?: AbortSignal): Promise<IPasskeySummary[]>;
+    renamePasskey(passkeyId: string, name: string, signal?: AbortSignal): Promise<void>;
+    deletePasskey(passkeyId: string, signal?: AbortSignal): Promise<void>;
     /**
      * Get current subscription for a workspace
      * Returns subscription details including plan, plan version, and group information
      */
-    getCurrentSubscription(workspaceId: string): Promise<ISubscriptionResponse>;
+    getCurrentSubscription(workspaceId: string, signal?: AbortSignal): Promise<ISubscriptionResponse>;
     /**
      * Get plan group for a workspace
      * Returns the plan group containing the current plan if subscription exists,
      * otherwise returns the latest published group
      */
-    getPlanGroup(workspaceId: string): Promise<IPlanGroupResponse>;
+    getPlanGroup(workspaceId: string, signal?: AbortSignal): Promise<IPlanGroupResponse>;
     /**
      * Get plan group for a workspace with a specific version
      * @param workspaceId - The workspace ID
      * @param groupVersionId - The plan group version ID to fetch
      * @returns Plan group response with the specified version
      */
-    getPlanGroupByVersion(workspaceId: string, groupVersionId: string): Promise<IPlanGroupResponse>;
+    getPlanGroupByVersion(workspaceId: string, groupVersionId: string, signal?: AbortSignal): Promise<IPlanGroupResponse>;
     /**
      * Get current group version and available newer versions of the same group
      * - If user has active subscription: returns their current group version + newer versions
@@ -1443,7 +1460,7 @@ declare class WorkspaceApi extends BaseApi {
      * @param workspaceId - The workspace ID
      * @returns Plan group versions response with currentVersion and availableVersions
      */
-    getPlanGroupVersions(workspaceId: string): Promise<IPlanGroupVersionsResponse>;
+    getPlanGroupVersions(workspaceId: string, signal?: AbortSignal): Promise<IPlanGroupVersionsResponse>;
     /**
      * Get plan group versions by slug (public, no auth required).
      * Returns the latest published plan group versions for the given plan group slug.
@@ -1452,7 +1469,7 @@ declare class WorkspaceApi extends BaseApi {
      * @param slug - Plan group slug (e.g. 'default', 'enterprise')
      * @returns Plan group versions response with currentVersion and availableVersions
      */
-    getPublicPlans(slug: string): Promise<IPublicPlansResponse>;
+    getPublicPlans(slug: string, signal?: AbortSignal): Promise<IPublicPlansResponse>;
     /**
      * Get credit packages (public, no auth required).
      * Returns active credit packages for the org with pricing info.
@@ -1460,7 +1477,7 @@ declare class WorkspaceApi extends BaseApi {
      *
      * @returns Credit packages with pricing variants
      */
-    getPublicCreditPackages(): Promise<IPublicCreditPackagesResponse>;
+    getPublicCreditPackages(signal?: AbortSignal): Promise<IPublicCreditPackagesResponse>;
     /**
      * Get plan group version details by ID (public, no auth required).
      * Returns the full plan group version with populated plan versions.
@@ -1469,15 +1486,24 @@ declare class WorkspaceApi extends BaseApi {
      * @param groupVersionId - The plan group version ID to fetch
      * @returns Plan group version with populated plan versions
      */
-    getPlanGroupVersion(groupVersionId: string): Promise<IPlanGroupVersion>;
+    getPlanGroupVersion(groupVersionId: string, signal?: AbortSignal): Promise<IPlanGroupVersion>;
     /**
      * Create checkout session for new subscription
      * @param workspaceId - The workspace ID
      * @param request - Checkout session request with planVersionId and optional billing interval/URLs
      * @returns Checkout session response with checkoutUrl to redirect user
      */
-    createCheckoutSession(workspaceId: string, request: ICheckoutSessionRequest): Promise<CheckoutResult>;
-    selectFreePlan(workspaceId: string, planVersionId: string): Promise<{
+    createCheckoutSession(workspaceId: string, request: ICheckoutSessionRequest, signal?: AbortSignal): Promise<CheckoutResult>;
+    /**
+     * Assign a free (freemium) plan to the workspace without a Stripe checkout.
+     *
+     * This endpoint's envelope carries no `data` payload — it is
+     * `{ success, message }` — so `fetchUnwrapped` resolves with the envelope
+     * itself (its unwrap only extracts `data` when present). On resolution
+     * `success` is therefore always `true`: non-2xx responses and 2xx envelopes
+     * with `success: false` both throw a structured Error.
+     */
+    selectFreePlan(workspaceId: string, planVersionId: string, signal?: AbortSignal): Promise<{
         success: boolean;
         message: string;
     }>;
@@ -1486,12 +1512,12 @@ declare class WorkspaceApi extends BaseApi {
      * Only allows plan changes within the same plan group
      * Returns checkout session if payment is required, otherwise returns subscription update response
      */
-    updateSubscription(workspaceId: string, request: ISubscriptionUpdateRequest): Promise<ISubscriptionUpdateResponse | ICheckoutSessionResponse>;
+    updateSubscription(workspaceId: string, request: ISubscriptionUpdateRequest, signal?: AbortSignal): Promise<ISubscriptionUpdateResponse | ICheckoutSessionResponse>;
     /**
      * Create a Stripe Customer Portal session for managing payment methods, invoices, etc.
      * Returns the portal URL — redirect user to it.
      */
-    createBillingPortalSession(workspaceId: string, returnUrl?: string): Promise<{
+    createBillingPortalSession(workspaceId: string, returnUrl?: string, signal?: AbortSignal): Promise<{
         url: string;
     }>;
     /**
@@ -1501,35 +1527,35 @@ declare class WorkspaceApi extends BaseApi {
      * @param startingAfter - Invoice ID to start after (for pagination)
      * @returns List of invoices with pagination info
      */
-    listInvoices(workspaceId: string, limit?: number, startingAfter?: string): Promise<IInvoiceListResponse>;
+    listInvoices(workspaceId: string, limit?: number, startingAfter?: string, signal?: AbortSignal): Promise<IInvoiceListResponse>;
     /**
      * Get a single invoice by ID
      * @param workspaceId - The workspace ID
      * @param invoiceId - The invoice ID
      * @returns Invoice details
      */
-    getInvoice(workspaceId: string, invoiceId: string): Promise<IInvoiceResponse>;
+    getInvoice(workspaceId: string, invoiceId: string, signal?: AbortSignal): Promise<IInvoiceResponse>;
     /**
      * Cancel subscription at the end of the current billing period
      * Sets cancelAtPeriodEnd: true - subscription remains active until period ends
      * @param workspaceId - The workspace ID
      * @returns Updated subscription with cancelAtPeriodEnd and stripeCurrentPeriodEnd
      */
-    cancelSubscriptionAtPeriodEnd(workspaceId: string): Promise<ISubscriptionResponse>;
+    cancelSubscriptionAtPeriodEnd(workspaceId: string, signal?: AbortSignal): Promise<ISubscriptionResponse>;
     /**
      * Resume a subscription that was scheduled for cancellation
      * Sets cancelAtPeriodEnd: false - subscription will continue after period ends
      * @param workspaceId - The workspace ID
      * @returns Updated subscription with cancelAtPeriodEnd set to false
      */
-    resumeSubscription(workspaceId: string): Promise<ISubscriptionResponse>;
+    resumeSubscription(workspaceId: string, signal?: AbortSignal): Promise<ISubscriptionResponse>;
     /**
      * Record quota usage for a workspace
      * @param workspaceId - The workspace ID
      * @param request - Usage request with quotaSlug, quantity, and optional metadata/source
      * @returns Usage result with consumed/included/available/overage
      */
-    recordUsage(workspaceId: string, request: IRecordUsageRequest): Promise<IRecordUsageResponse>;
+    recordUsage(workspaceId: string, request: IRecordUsageRequest, signal?: AbortSignal): Promise<IRecordUsageResponse>;
     /**
      * Record multiple quota usage entries in a single request.
      * Designed for backend-to-backend high-volume scenarios (bulk exports, batch jobs).
@@ -1553,7 +1579,7 @@ declare class WorkspaceApi extends BaseApi {
             source?: string;
             idempotencyKey?: string;
         }>;
-    }): Promise<{
+    }, signal?: AbortSignal): Promise<{
         success: boolean;
         total: number;
         succeeded: number;
@@ -1571,20 +1597,20 @@ declare class WorkspaceApi extends BaseApi {
      * @param quotaSlug - The quota slug to check
      * @returns Quota usage status with consumed/included/available/overage/hasOverage
      */
-    getQuotaUsageStatus(workspaceId: string, quotaSlug: string): Promise<IQuotaUsageStatusResponse>;
+    getQuotaUsageStatus(workspaceId: string, quotaSlug: string, signal?: AbortSignal): Promise<IQuotaUsageStatusResponse>;
     /**
      * Get usage status for all quotas in the workspace's current plan
      * @param workspaceId - The workspace ID
      * @returns All quota usage statuses keyed by quota slug
      */
-    getAllQuotaUsage(workspaceId: string): Promise<IAllQuotaUsageResponse>;
+    getAllQuotaUsage(workspaceId: string, signal?: AbortSignal): Promise<IAllQuotaUsageResponse>;
     /**
      * Get paginated usage logs for a workspace
      * @param workspaceId - The workspace ID
      * @param query - Optional filters: quotaSlug, from, to, source, page, limit
      * @returns Paginated usage log entries
      */
-    getUsageLogs(workspaceId: string, query?: IUsageLogsQuery): Promise<IUsageLogsResponse>;
+    getUsageLogs(workspaceId: string, query?: IUsageLogsQuery, signal?: AbortSignal): Promise<IUsageLogsResponse>;
     /**
      * Trigger a notification event for a workspace.
      * Respects all notification gates (org settings, event config, workspace preferences).
@@ -1607,16 +1633,16 @@ declare class WorkspaceApi extends BaseApi {
      * });
      * ```
      */
-    sendNotification(workspaceId: string, event: string, userId?: string, data?: NotificationData): Promise<NotificationResult>;
-    getNotificationEvents(workspaceId: string): Promise<NotificationEvent[]>;
-    getNotificationPreferences(workspaceId: string): Promise<Record<string, {
+    sendNotification(workspaceId: string, event: string, userId?: string, data?: NotificationData, signal?: AbortSignal): Promise<NotificationResult>;
+    getNotificationEvents(workspaceId: string, signal?: AbortSignal): Promise<NotificationEvent[]>;
+    getNotificationPreferences(workspaceId: string, signal?: AbortSignal): Promise<Record<string, {
         email?: boolean;
         push?: boolean;
     }>>;
     updateNotificationPreferences(workspaceId: string, preferences: Record<string, {
         email?: boolean;
         push?: boolean;
-    }>): Promise<Record<string, {
+    }>, signal?: AbortSignal): Promise<Record<string, {
         email?: boolean;
         push?: boolean;
     }>>;
@@ -1625,7 +1651,7 @@ declare class WorkspaceApi extends BaseApi {
      * @param workspaceId - The workspace ID
      * @returns Credit balance with available, totalGranted, totalConsumed, totalExpired, totalRefunded
      */
-    getCreditBalance(workspaceId: string): Promise<ICreditBalance>;
+    getCreditBalance(workspaceId: string, signal?: AbortSignal): Promise<ICreditBalance>;
     /**
      * Consume credits from a workspace balance.
      * Throws an error with `code: 'INSUFFICIENT_CREDITS'` and `available`/`requested` fields on 402.
@@ -1633,7 +1659,7 @@ declare class WorkspaceApi extends BaseApi {
      * @param request - Consume request with amount, optional description, idempotencyKey, metadata
      * @returns Consume result with consumed amount and balanceAfter
      */
-    consumeCredits(workspaceId: string, request: IConsumeCreditsRequest): Promise<IConsumeCreditsResponse>;
+    consumeCredits(workspaceId: string, request: IConsumeCreditsRequest, signal?: AbortSignal): Promise<IConsumeCreditsResponse>;
     /**
      * Create a Stripe checkout session for purchasing a credit package.
      * Returns a checkout URL to redirect the user to.
@@ -1641,35 +1667,35 @@ declare class WorkspaceApi extends BaseApi {
      * @param request - Purchase request with creditPackageId, successUrl, cancelUrl, optional currency
      * @returns Checkout session ID and URL
      */
-    purchaseCredits(workspaceId: string, request: ICreditPurchaseRequest): Promise<ICreditPurchaseResponse>;
+    purchaseCredits(workspaceId: string, request: ICreditPurchaseRequest, signal?: AbortSignal): Promise<ICreditPurchaseResponse>;
     /**
      * List available credit packages for purchase.
      * Returns active, non-archived packages sorted by sortOrder then creditAmount.
      * @param workspaceId - The workspace ID
      * @returns Array of credit packages
      */
-    getCreditPackages(workspaceId: string): Promise<ICreditPackage[]>;
+    getCreditPackages(workspaceId: string, signal?: AbortSignal): Promise<ICreditPackage[]>;
     /**
      * Get paginated credit transaction history.
      * @param workspaceId - The workspace ID
      * @param query - Optional filters: type, page, limit
      * @returns Paginated credit transactions
      */
-    getCreditTransactions(workspaceId: string, query?: ICreditTransactionsQuery): Promise<ICreditTransactionsResponse>;
+    getCreditTransactions(workspaceId: string, query?: ICreditTransactionsQuery, signal?: AbortSignal): Promise<ICreditTransactionsResponse>;
     /**
      * Get paginated credit buckets.
      * @param workspaceId - The workspace ID
      * @param query - Optional filters: status, source, page, limit
      * @returns Paginated credit buckets
      */
-    getCreditBuckets(workspaceId: string, query?: ICreditBucketsQuery): Promise<ICreditBucketsResponse>;
+    getCreditBuckets(workspaceId: string, query?: ICreditBucketsQuery, signal?: AbortSignal): Promise<ICreditBucketsResponse>;
     /**
      * Get credits expiring within N days.
      * @param workspaceId - The workspace ID
      * @param days - Look-ahead window in days (1-90, default 7)
      * @returns Expiring credits summary with bucket list
      */
-    getExpiringCredits(workspaceId: string, days?: number): Promise<IExpiringCreditsResponse>;
+    getExpiringCredits(workspaceId: string, days?: number, signal?: AbortSignal): Promise<IExpiringCreditsResponse>;
 }
 
 /**
@@ -1796,6 +1822,7 @@ declare const BBAction: {
     readonly SelectPlan: "selectPlan";
     readonly CreditPurchase: "creditPurchase";
     readonly OpenCreditStore: "openCreditStore";
+    readonly OpenConnectGuide: "openConnectGuide";
     readonly Invite: "invite";
 };
 type BBActionType = (typeof BBAction)[keyof typeof BBAction];
@@ -1953,14 +1980,33 @@ declare const PLAN_CURRENCY_OPTIONS: {
     value: "usd" | "eur" | "gbp" | "jpy" | "cad" | "aud" | "chf" | "cny" | "hkd" | "sgd" | "inr" | "mxn" | "brl" | "nzd" | "sek" | "nok" | "dkk" | "pln" | "thb";
     label: string;
 }[];
+/**
+ * Minor-unit digits for a currency per ISO 4217: 0 (JPY, KRW, …), 2 (most),
+ * or 3 (KWD, BHD, …). The zero- and three-decimal sets are pinned to Stripe's
+ * treatment (the billing backend defines amount semantics); ISK is pinned to 2
+ * (Stripe legacy — ISO 4217 says 0). Any other code defers to the runtime's
+ * CLDR data (IQD/LYD → 3, CLF/UYW → 4, UYI → 0), falling back to 2 for codes
+ * unknown to Intl or malformed.
+ */
+declare function getCurrencyDecimals(currency: string | null | undefined): number;
 /** True when `currency` has no minor unit (JPY, KRW, …) — amounts are whole units, not cents. */
 declare function isZeroDecimalCurrency(currency: string | null | undefined): boolean;
 /**
  * Convert a minor-unit amount to its display number for `currency`:
  * `minorAmountToDisplay(1999, 'usd')` → `"19.99"`,
- * `minorAmountToDisplay(1000, 'jpy')` → `"1,000"` (zero-decimal — no division).
+ * `minorAmountToDisplay(1000, 'jpy')` → `"1,000"` (zero-decimal — no division),
+ * `minorAmountToDisplay(12345, 'kwd')` → `"12.345"` (three-decimal — ÷1000).
  */
 declare function minorAmountToDisplay(amount: number, currency: string): string;
+/**
+ * Locale-aware currency formatting of a minor-unit amount via `Intl.NumberFormat`
+ * (`(1999, 'usd', 'en-US')` → `"$19.99"`; `(1000, 'jpy', 'ja-JP')` → `"￥1,000"`;
+ * `(12345, 'kwd')` → `"KWD 12.345"`). The divisor follows the currency's ISO 4217
+ * minor-unit digits (see `getCurrencyDecimals`) — zero-decimal currencies are
+ * never divided, three-decimal divide by 1000. Falls back to the symbol table
+ * when the currency code is empty or malformed.
+ */
+declare function formatMinorAmountIntl(amount: number, currency: string, locale?: string): string;
 /** Format cents as money string (e.g. 1999, "usd" -> "$19.99"; 1000, "jpy" -> "¥1,000"). Caller must pass currency (e.g. from plan or workspace). */
 declare function formatCents(cents: number, currency: string): string;
 /** Translatable labels for overage/quota formatting */
@@ -1980,15 +2026,16 @@ interface OverageLabels {
 }
 /**
  * Format overage rate for display. When unitSize > 1: "$1.00/1,000 units"; else "$1.00/unit".
- * Pass `labels` for i18n support.
+ * Pass `labels` for i18n support and `locale` to group numbers in the display locale.
  */
-declare function formatOverageRate(overageCents: number | undefined, unitSize: number | undefined, currency: string, labels?: Partial<OverageLabels>): string | null;
+declare function formatOverageRate(overageCents: number | undefined, unitSize: number | undefined, currency: string, labels?: Partial<OverageLabels>, locale?: string): string | null;
 /**
  * Format overage rate with optional unit label for comparison/preview UIs.
  * e.g. formatOverageRateWithLabel(50, 1000, "video", "usd") -> "$0.50/1,000 videos"
  * Pass `labels` for i18n support. Pass `pluralUnitLabel` to avoid English "s" pluralization.
+ * Pass `locale` to group numbers in the display locale.
  */
-declare function formatOverageRateWithLabel(overageCents: number | undefined, unitSize: number | undefined, unitLabel: string | undefined, currency: string, pluralUnitLabel?: string, labels?: Partial<OverageLabels>): string | null;
+declare function formatOverageRateWithLabel(overageCents: number | undefined, unitSize: number | undefined, unitLabel: string | undefined, currency: string, pluralUnitLabel?: string, labels?: Partial<OverageLabels>, locale?: string): string | null;
 /**
  * Get singular unit label from item name or slug (e.g. "Videos" -> "video", "reels" -> "reel").
  * Used for quota display in comparison and preview.
@@ -1997,9 +2044,10 @@ declare function formatOverageRateWithLabel(overageCents: number | undefined, un
 declare function getQuotaUnitLabelFromName(nameOrSlug: string, fallback?: string): string;
 /**
  * Format quota "included + overage" for display.
- * Pass `labels` and `pluralUnitLabel` for i18n support.
+ * Pass `labels` and `pluralUnitLabel` for i18n support, and `locale` to group
+ * numbers in the display locale.
  */
-declare function formatQuotaIncludedOverage(included: number | undefined, overageCents: number | undefined, unitLabel: string, currency: string, unitSize?: number, pluralUnitLabel?: string, labels?: Partial<OverageLabels>, allowOverage?: boolean): string;
+declare function formatQuotaIncludedOverage(included: number | undefined, overageCents: number | undefined, unitLabel: string, currency: string, unitSize?: number, pluralUnitLabel?: string, labels?: Partial<OverageLabels>, allowOverage?: boolean, locale?: string): string;
 
 type QuotaDisplayValue = {
     included: number;
@@ -2031,6 +2079,8 @@ interface QuotaLabels {
     included: string;
     /** e.g. "then" — separator between included and price */
     then: string;
+    /** e.g. "hard limit" — shown when overage is not allowed */
+    hardLimit?: string;
 }
 /**
  * Format a quota display value as "X included, then $Y.YY / unit".
@@ -2158,6 +2208,18 @@ declare function validateInvite(opts: {
     requireSubscription?: boolean;
 }): InviteValidation;
 
+/** Minimal workspace shape needed for ownership/role checks. Extended by `permissions.WorkspaceLike`. */
+interface WorkspaceLike$1 {
+    _id: string;
+    createdBy: string | {
+        _id: string;
+    } | null | undefined;
+    users?: Array<string | {
+        _id: string;
+        role?: string;
+    }>;
+}
+
 /**
  * Role-based permission system.
  * Framework-agnostic — used by both React hooks and server-side BuildBase.
@@ -2175,6 +2237,7 @@ declare function validateInvite(opts: {
  * Both are resolved from the same role→permission map. Owner always gets all
  * platform permissions + any app permissions defined in the config.
  */
+
 declare const Permission: {
     readonly WORKSPACE_SETTINGS_VIEW: "workspace:settings:view";
     readonly WORKSPACE_SETTINGS_EDIT: "workspace:settings:edit";
@@ -2192,15 +2255,7 @@ declare const Permission: {
 type PermissionKey = (typeof Permission)[keyof typeof Permission];
 type RolePermissionMap = Record<string, string[]>;
 declare const DEFAULT_ROLE_PERMISSIONS: RolePermissionMap;
-interface WorkspaceLike {
-    _id: string;
-    createdBy: string | {
-        _id: string;
-    } | null | undefined;
-    users?: Array<string | {
-        _id: string;
-        role?: string;
-    }>;
+interface WorkspaceLike extends WorkspaceLike$1 {
     permissions?: Record<string, string[]>;
 }
 interface SettingsLike {
@@ -2257,7 +2312,7 @@ declare function hasPermission(permission: string | string[], ctx: PermissionCon
  *
  * Or manually create `public/push-sw.js` with this content.
  */
-declare const PUSH_SERVICE_WORKER_SCRIPT = "\n// BuildBase Push Notification Service Worker\n// Place this file in your app's public directory (e.g. public/push-sw.js)\n\nself.addEventListener('push', function(event) {\n  if (!event.data) return;\n\n  try {\n    const payload = event.data.json();\n    const title = payload.title || 'Notification';\n    const options = {\n      body: payload.body || '',\n      icon: payload.icon || undefined,\n      badge: payload.icon || undefined,\n      data: { url: payload.url, ...(payload.data || {}) },\n      tag: 'buildbase-push-' + Date.now(),\n    };\n\n    event.waitUntil(\n      self.registration.showNotification(title, options)\n    );\n  } catch (e) {\n    console.error('[PushSW] Failed to show notification:', e);\n  }\n});\n\nself.addEventListener('notificationclick', function(event) {\n  event.notification.close();\n\n  const url = event.notification.data && event.notification.data.url;\n  if (url) {\n    event.waitUntil(\n      clients.matchAll({ type: 'window', includeUncontrolled: true }).then(function(clientList) {\n        for (let i = 0; i < clientList.length; i++) {\n          const client = clientList[i];\n          if (client.url === url && 'focus' in client) {\n            return client.focus();\n          }\n        }\n        if (clients.openWindow) {\n          return clients.openWindow(url);\n        }\n      })\n    );\n  }\n});\n";
+declare const PUSH_SERVICE_WORKER_SCRIPT = "\n// BuildBase Push Notification Service Worker\n// Place this file in your app's public directory (e.g. public/push-sw.js)\n\nself.addEventListener('push', function(event) {\n  if (!event.data) return;\n\n  try {\n    const payload = event.data.json();\n    // i18n exception: service workers run outside the SDK's translation\n    // provider, so this last-resort fallback stays English. The server should\n    // always send a localized payload.title.\n    const title = payload.title || 'Notification';\n    const options = {\n      body: payload.body || '',\n      icon: payload.icon || undefined,\n      badge: payload.icon || undefined,\n      data: { url: payload.url, ...(payload.data || {}) },\n      tag: 'buildbase-push-' + Date.now(),\n    };\n\n    event.waitUntil(\n      self.registration.showNotification(title, options)\n    );\n  } catch (e) {\n    console.error('[PushSW] Failed to show notification:', e);\n  }\n});\n\nself.addEventListener('notificationclick', function(event) {\n  event.notification.close();\n\n  const url = event.notification.data && event.notification.data.url;\n  if (url) {\n    event.waitUntil(\n      clients.matchAll({ type: 'window', includeUncontrolled: true }).then(function(clientList) {\n        for (let i = 0; i < clientList.length; i++) {\n          const client = clientList[i];\n          if (client.url === url && 'focus' in client) {\n            return client.focus();\n          }\n        }\n        if (clients.openWindow) {\n          return clients.openWindow(url);\n        }\n      })\n    );\n  }\n});\n";
 
 interface BetaFormData {
     name?: string;
@@ -2280,6 +2335,24 @@ interface SDKMessages {
         connectedAgentsEmpty: string;
         connectedAgentsAccess: string;
         connectedAgentsGranted: string;
+        connectedAgentsLoadFailed: string;
+        connectedAgentsRevokeFailed: string;
+        mcpConnectAction: string;
+        mcpGuideTitle: string;
+        mcpGuideDescription: string;
+        mcpServerUrlLabel: string;
+        mcpServerUrlHint: string;
+        mcpPromptLabel: string;
+        mcpPromptHint: string;
+        mcpPromptTemplate: string;
+        mcpClientsLabel: string;
+        mcpAddToConfigFile: string;
+        mcpClientChatgptInstructions: string;
+        mcpClientClaudeInstructions: string;
+        mcpClientClineInstructions: string;
+        mcpCopy: string;
+        mcpCopied: string;
+        mcpLearnMore: string;
         inactive: string;
         inactiveHint: string;
         passkeysTitle: string;
@@ -2343,6 +2416,7 @@ interface SDKMessages {
             billingManageOnly: string;
             openSettings: string;
             back: string;
+            close: string;
         };
     };
     subscription: {
@@ -2629,6 +2703,7 @@ interface SDKMessages {
         featureSuccess: string;
         updateSuccess: string;
         actionStatus: string;
+        fallbackName: string;
     };
     danger: {
         title: string;
@@ -2849,6 +2924,7 @@ interface SDKMessages {
         purchaseFailed: string;
         errorLoading: string;
         insufficientCredits: string;
+        insufficientDetail: string;
     };
     loading: {
         restoringSession: string;
@@ -2884,6 +2960,7 @@ interface SDKMessages {
         fetchCreditPackages: string;
         fetchCreditTransactions: string;
         fetchExpiringCredits: string;
+        fetchWorkspaces: string;
     };
 }
 /** Supported locale codes */
@@ -2954,6 +3031,88 @@ interface FullScreenLoaderContextValue {
  */
 declare function useFullScreenLoader(): FullScreenLoaderContextValue;
 
+/**
+ * Setup steps for one app/tool a person can connect to the server, shown as an
+ * expandable row in the connect guide. In `instructions` and `snippet` you can
+ * use these placeholders, filled in at render time:
+ * `{{url}}` (server address), `{{name}}` (display name), `{{key}}` (a short
+ * safe id used as the key inside config files).
+ */
+interface McpClientGuide {
+    /** Stable identifier (React key). */
+    id: string;
+    /** Display name shown on the row, e.g. `"Cursor"`. Not translated (proper noun). */
+    name: string;
+    /** Plain-language steps shown above the snippet (what to click / where to paste). */
+    instructions?: string;
+    /** A config snippet the person copies and pastes. Usually JSON. */
+    snippet?: string;
+    /** Optional button link (e.g. a one-click install deep link). */
+    actionUrl?: string;
+    /** Label for {@link actionUrl}. */
+    actionLabel?: string;
+}
+/**
+ * MCP connection info passed to `SaaSOSProvider` via the `mcp` prop. Drives the
+ * "Connect an agent" guide on the Connected Agents screen. The guide only
+ * renders when `url` is set.
+ *
+ * @example
+ * ```tsx
+ * <SaaSOSProvider
+ *   mcp={{
+ *     url: 'https://app.example.com/api/mcp',
+ *     name: 'Acme',
+ *     docsUrl: 'https://docs.example.com/agents',
+ *   }}
+ * >
+ * ```
+ */
+interface McpConnectionConfig {
+    /** MCP server endpoint URL. Required — the guide renders only when set. */
+    url: string;
+    /** Friendly server name used in prose and snippets. Defaults to `'app'`. */
+    name?: string;
+    /** "Learn more" docs link shown at the bottom of the guide. */
+    docsUrl?: string;
+    /**
+     * The app/tool setup rows. When omitted, a translated built-in set covering
+     * the major AI apps (ChatGPT, Claude, Cursor, VS Code, Windsurf, Cline) is
+     * used. Provide your own to override or extend.
+     */
+    clients?: McpClientGuide[];
+    /**
+     * The copy-and-paste prompt shown for chat-style AIs ("paste this to connect").
+     * Defaults to a translated sentence; pass a string to customize (supports
+     * `{{url}}`/`{{name}}`), or `false` (or an empty string) to hide the prompt
+     * block entirely.
+     */
+    prompt?: string | false;
+}
+/**
+ * Fill `{{url}}` / `{{name}}` / `{{key}}` (and any extra vars) placeholders in a
+ * guide template. Single pass, so a value that itself contains `{{…}}` text is
+ * never re-substituted; unknown placeholders are left untouched.
+ *
+ * Values are inserted **verbatim** — when a template is JSON (a client
+ * `snippet`), pass values that are already valid inside a JSON string (the
+ * built-in snippets only interpolate the URL and the JSON-safe {@link mcpServerKey}).
+ */
+declare function fillMcpTemplate(template: string | undefined, vars: Record<string, string>): string | undefined;
+/**
+ * A short, file-safe id derived from a display name — used as the `{{key}}`
+ * (the JSON key inside config-file snippets). Always `[a-z0-9-]+`, so it is
+ * safe to drop into JSON unescaped; falls back to `'app'` when the name has no
+ * ASCII alphanumerics (e.g. a non-Latin name).
+ */
+declare function mcpServerKey(name: string): string;
+/**
+ * The MCP connection config passed to `SaaSOSProvider`, or `null` when none was
+ * provided. Use it to build a custom connect guide; the ready-made UI is
+ * `<ConnectMcpGuide />` (and it's embedded in `<ConnectedAgents />`).
+ */
+declare function useMcpConnection(): McpConnectionConfig | null;
+
 /**
  * Settings screen identifiers — kept in a leaf module (no component imports)
  * so consumers of `SettingsScreen` don't pull the whole settings dialog
@@ -3227,6 +3386,23 @@ interface SaaSOSProviderProps extends IOsState {
      * ```
      */
     ui?: SDKUIConfig;
+    /**
+     * MCP server connection info. When set, the Connected Agents screen shows a
+     * "How to connect an agent" guide (copyable server URL + per-client setup
+     * snippets). Read anywhere via `useMcpConnection()`.
+     *
+     * @example
+     * ```tsx
+     * <SaaSOSProvider
+     *   mcp={{
+     *     url: 'https://app.example.com/api/mcp',
+     *     name: 'Acme',
+     *     docsUrl: 'https://docs.example.com/agents',
+     *   }}
+     * >
+     * ```
+     */
+    mcp?: McpConnectionConfig;
 }
 declare const SaaSOSProvider: React__default.FC<SaaSOSProviderProps>;
 
@@ -3517,16 +3693,49 @@ interface ConnectedAgentsProps {
     disconnectLabel?: string;
     /** Text shown when the user has no connected agents. Defaults to the translated label. */
     emptyLabel?: string;
+    /**
+     * Show the "Connect an agent" action (a header button + empty-state CTA that
+     * open the setup guide in a dialog). Defaults to `true` when an `mcp` config
+     * is passed to `SaaSOSProvider`; set `false` to hide it even when configured.
+     */
+    showConnectGuide?: boolean;
 }
 /**
  * A ready-made "Connected agents" screen: lists the AI agents the signed-in user
- * has authorized to access their account, with a per-row Disconnect action.
- * Session-authed and scoped to the current user — no config beyond having the
- * app wrapped in <SaaSOSProvider>.
+ * has authorized to access their account, with a per-row Disconnect action. When
+ * an `mcp` config is set on `SaaSOSProvider`, a "Connect an agent" button (header
+ * + empty state) opens a setup-guide dialog. Session-authed and scoped to the
+ * current user — no config beyond having the app wrapped in <SaaSOSProvider>.
+ *
+ * As a workspace settings screen, open it programmatically with
+ * `openWorkspaceSettings('connected-agents')`; add `{ action: 'openConnectGuide' }`
+ * (or `?bb=action:openConnectGuide`) to land straight on the setup dialog.
+ *
+ * For a fully custom UI, use the `useConnectedAgents()` hook and `<ConnectMcpGuide />`.
+ */
+declare function ConnectedAgents({ className, title, description, disconnectLabel, emptyLabel, showConnectGuide, }: ConnectedAgentsProps): react_jsx_runtime.JSX.Element;
+
+interface ConnectMcpGuideProps {
+    /**
+     * Connection config. Defaults to the `mcp` prop passed to `SaaSOSProvider`
+     * (via `useMcpConnection()`); pass explicitly to render a guide elsewhere.
+     */
+    config?: McpConnectionConfig | null;
+    /** Heading. Defaults to the translated title; `null` hides it. */
+    title?: string | null;
+    /** Sub-heading. Defaults to the translated description; `null` hides it. */
+    description?: string | null;
+    className?: string;
+}
+/**
+ * A friendly "Connect an agent" guide: the server address, a copy-and-paste
+ * prompt for chat assistants, and step-by-step setup for the major AI apps
+ * (ChatGPT, Claude, Cursor, VS Code, Windsurf, Cline by default; override via
+ * `config.clients`). Renders `null` when no MCP `url` is configured.
  *
- * For a fully custom UI, use the `useConnectedAgents()` hook instead.
+ * Shown inside `<ConnectedAgents />`; also exported for standalone use.
  */
-declare function ConnectedAgents({ className, title, description, disconnectLabel, emptyLabel, }: ConnectedAgentsProps): react_jsx_runtime.JSX.Element;
+declare function ConnectMcpGuide({ config, title, description, className }: ConnectMcpGuideProps): react_jsx_runtime.JSX.Element | null;
 
 interface IProps {
     slug: string;
@@ -3618,9 +3827,9 @@ declare const WhenWorkspaceFeatureDisabled: {
  * ```tsx
  * // Edge case: Feature not loaded yet
  * function FeatureContent() {
- *   const { isLoading } = useUserFeatures();
+ *   const { loading } = useUserFeatures();
  *
- *   if (isLoading) return <Loading />;
+ *   if (loading) return <Loading />;
  *
  *   return (
  *     <WhenUserFeatureEnabled slug="feature-x">
@@ -4029,7 +4238,7 @@ interface CreditActionsProviderProps {
  *
  *       {packages.map(pkg => (
  *         <button key={pkg._id} onClick={() => purchase(pkg)} disabled={purchasing}>
- *           Buy {pkg.creditAmount} for ${pkg.pricingVariants[0]?.amount / 100}
+ *           Buy {pkg.creditAmount} for {formatCents(pkg.pricingVariants[0]?.amount ?? 0, pkg.pricingVariants[0]?.currency ?? 'usd')}
  *         </button>
  *       ))}
  *     </div>
@@ -4145,7 +4354,7 @@ interface CreditStorePageProps {
  *           <div key={pkg._id}>
  *             <h3>{pkg.name}</h3>
  *             <p>{pkg.creditAmount} credits</p>
- *             <p>${(pkg.pricingVariants[0]?.amount / 100).toFixed(2)}</p>
+ *             <p>{formatCents(pkg.pricingVariants[0]?.amount ?? 0, pkg.pricingVariants[0]?.currency ?? 'usd')}</p>
  *             <button onClick={() => selectPackage(pkg._id)}>Buy</button>
  *           </div>
  *         ))}
@@ -4359,51 +4568,40 @@ declare function useSaaSOs(): IOsState;
  * Hook to access organization settings from the OS context.
  * Automatically fetches settings once when OS config is ready.
  * Safe to call from multiple components — only one fetch is made.
+ *
+ * @returns `{ settings, loading, error, refetch }` — `loading` is true from
+ * mount until the one-time fetch settles (so UI can wait instead of guessing
+ * with `?? true` defaults); `error` carries the failure message; `refetch`
+ * re-runs the fetch (deduped across components).
  */
 declare function useSaaSSettings(): {
     settings: ISettings | null | undefined;
+    loading: boolean;
+    error: string | null;
+    refetch: (_signal?: AbortSignal) => Promise<ISettings | null>;
     getSettings: (_signal?: AbortSignal) => Promise<ISettings | null>;
 };
 
-interface UserContextValue {
-    attributes: Record<string, string | number | boolean>;
-    features: Record<string, boolean>;
-    /** True while EITHER pipeline is loading. Prefer the per-resource flags. */
-    isLoading: boolean;
-    /** The first per-resource error, attributes first. Prefer the per-resource errors. */
-    error: Error | null;
-    /** True while attributes are loading (independent of features). */
-    attributesLoading: boolean;
-    /** True while features are loading (independent of attributes). */
-    featuresLoading: boolean;
-    /** Last attributes fetch/update error; cleared when a new attributes request starts. */
-    attributesError: Error | null;
-    /** Last features fetch error; cleared when a new features request starts. */
-    featuresError: Error | null;
-    updateAttributes: (updates: Record<string, string | number | boolean>) => Promise<IUser>;
-    updateAttribute: (attributeKey: string, value: string | number | boolean) => Promise<IUser>;
-    refreshAttributes: () => Promise<void>;
-    refreshFeatures: () => Promise<void>;
-}
-
 /**
  * Hook to access user attributes from the UserProvider.
  * Must be used within a UserProvider component.
  *
- * @returns User context object containing:
+ * @returns An object containing:
  * - `attributes`: Record of user attribute key-value pairs
- * - `isLoading`: Boolean indicating if attributes are being loaded
- * - `error`: Error message string (null if no error)
- * - `refreshAttributes()`: Function to manually refresh attributes
+ * - `loading`: Boolean indicating if attributes are being loaded (attributes pipeline only)
+ * - `error`: Last attributes fetch/update error (null if no error)
+ * - `refetch()`: Function to manually refresh attributes
+ * - `updateAttributes(updates)`: Function to update multiple attributes
+ * - `updateAttribute(key, value)`: Function to update one attribute
  *
  * @throws {Error} If used outside of UserProvider
  *
  * @example
  * ```tsx
  * function UserProfile() {
- *   const { attributes, isLoading } = useUserAttributes();
+ *   const { attributes, loading } = useUserAttributes();
  *
- *   if (isLoading) return <Loading />;
+ *   if (loading) return <Loading />;
  *
  *   return (
  *     <div>
@@ -4414,16 +4612,27 @@ interface UserContextValue {
  * }
  * ```
  */
-declare function useUserAttributes(): UserContextValue;
+declare function useUserAttributes(): {
+    attributes: Record<string, string | number | boolean>;
+    loading: boolean;
+    error: Error | null;
+    refetch: () => Promise<void>;
+    updateAttributes: (updates: Record<string, string | number | boolean>) => Promise<IUser>;
+    updateAttribute: (attributeKey: string, value: string | number | boolean) => Promise<IUser>;
+    /** @deprecated Use `loading` (note: this legacy flag combines BOTH pipelines). */
+    isLoading: boolean;
+    /** @deprecated Use `refetch`. */
+    refreshAttributes: () => Promise<void>;
+};
 /**
  * Hook to access user feature flags from the UserProvider.
  * Must be used within a UserProvider component.
  *
  * @returns An object containing:
  * - `features`: Record of feature flag key-value pairs (boolean values)
- * - `isLoading`: Boolean indicating if features are being loaded
- * - `error`: Error message string (null if no error)
- * - `refreshFeatures()`: Function to manually refresh features
+ * - `loading`: Boolean indicating if features are being loaded (features pipeline only)
+ * - `error`: Last features fetch error (null if no error)
+ * - `refetch()`: Function to manually refresh features
  * - `isFeatureEnabled(featureId)`: Function to check if a specific feature is enabled
  *
  * @throws {Error} If used outside of UserProvider
@@ -4431,9 +4640,9 @@ declare function useUserAttributes(): UserContextValue;
  * @example
  * ```tsx
  * function FeatureContent() {
- *   const { isFeatureEnabled, isLoading } = useUserFeatures();
+ *   const { isFeatureEnabled, loading } = useUserFeatures();
  *
- *   if (isLoading) return <Loading />;
+ *   if (loading) return <Loading />;
  *
  *   if (isFeatureEnabled('premium-feature')) {
  *     return <PremiumFeature />;
@@ -4460,20 +4669,130 @@ declare function useUserAttributes(): UserContextValue;
  */
 declare function useUserFeatures(): {
     features: Record<string, boolean>;
-    isLoading: boolean;
+    loading: boolean;
     error: Error | null;
-    refreshFeatures: () => Promise<void>;
+    refetch: () => Promise<void>;
     isFeatureEnabled: (featureId: string) => boolean;
+    /** @deprecated Use `loading`. */
+    isLoading: boolean;
+    /** @deprecated Use `refetch`. */
+    refreshFeatures: () => Promise<void>;
 };
 
+/**
+ * Main workspace management hook for the SDK.
+ * Provides workspace state, CRUD operations, and user management.
+ *
+ * State selection is per-consumer; the lifecycle (fetch dedup, storage
+ * restore, switch versioning, current-workspace sync) lives in the single
+ * `WorkspaceProvider` instance mounted by `SaaSOSProvider`, so
+ * `onWorkspaceChange` / `workspace:changed` fire exactly once per switch no
+ * matter how many components use this hook.
+ *
+ * @returns An object containing:
+ * - `workspaces`: Array of all workspaces the user has access to
+ * - `currentWorkspace`: Currently selected workspace (null if none selected)
+ * - `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 - 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 (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
+ * - `deleteWorkspace(workspaceId)`: Function to delete a workspace (owner only)
+ * - `getWorkspace(workspaceId)`: Function to fetch a specific workspace
+ * - `getUsers(workspaceId)`: Function to fetch users in a workspace
+ * - `addUser(workspaceId, email, role)`: Function to add a user to a workspace
+ * - `removeUser(workspaceId, userId)`: Function to remove a user from a workspace
+ * - `updateUser(workspaceId, userId, config)`: Function to update a user in a workspace
+ * - `getProfile()`: Function to fetch current user profile
+ * - `updateUserProfile(config)`: Function to update current user profile
+ * - `allFeatures`: Array of all available feature flags
+ * - `getFeatures()`: Function to fetch all available features
+ * - `updateFeature(workspaceId, key, value)`: Function to update a feature flag
+ *
+ * @example
+ * ```tsx
+ * function WorkspaceList() {
+ *   const { workspaces, loading, fetchWorkspaces } = useSaaSWorkspaces();
+ *
+ *   useEffect(() => {
+ *     fetchWorkspaces();
+ *   }, [fetchWorkspaces]);
+ *
+ *   if (loading) return <Loading />;
+ *
+ *   return (
+ *     <ul>
+ *       {workspaces.map(ws => (
+ *         <li key={ws._id}>{ws.name}</li>
+ *       ))}
+ *     </ul>
+ *   );
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Create a new workspace
+ * function CreateWorkspace() {
+ *   const { createWorkspace } = useSaaSWorkspaces();
+ *
+ *   const handleCreate = async () => {
+ *     try {
+ *       await createWorkspace('My Workspace', 'https://example.com/logo.png');
+ *     } catch (error) {
+ *       console.error('Failed to create workspace:', error);
+ *     }
+ *   };
+ *
+ *   return <button onClick={handleCreate}>Create Workspace</button>;
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Delete workspace (owner only)
+ * function DeleteWorkspaceButton({ workspaceId }) {
+ *   const { deleteWorkspace } = useSaaSWorkspaces();
+ *
+ *   const handleDelete = async () => {
+ *     if (!confirm('Are you sure?')) return;
+ *     try {
+ *       await deleteWorkspace(workspaceId);
+ *     } catch (error) {
+ *       // Error: "Only the workspace creator can delete the workspace"
+ *       alert(error.message);
+ *     }
+ *   };
+ *
+ *   return <button onClick={handleDelete}>Delete</button>;
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Edge case: Workspace removed from user's access
+ * function WorkspaceContent() {
+ *   const { currentWorkspace, workspaces } = useSaaSWorkspaces();
+ *
+ *   // If current workspace is not in the list, it was removed
+ *   // The hook automatically switches to first available workspace
+ *   if (!currentWorkspace) {
+ *     return <p>No workspace selected</p>;
+ *   }
+ *
+ *   return <div>{currentWorkspace.name}</div>;
+ * }
+ * ```
+ */
 declare const useSaaSWorkspaces: () => {
-    workspaces: IWorkspace[];
-    loading: boolean;
-    error: string | null;
     fetchWorkspaces: () => Promise<void>;
     refreshWorkspaces: () => Promise<void>;
-    refreshing: boolean;
-    currentWorkspace: IWorkspace | null;
     setCurrentWorkspace: (ws: IWorkspace, options?: {
         forceEmit?: boolean;
     }) => void;
@@ -4482,25 +4801,15 @@ declare const useSaaSWorkspaces: () => {
     }) => 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>;
-    updateWorkspaceSettings: (data: {
-        permissions: Record<string, string[]>;
-    }) => Promise<any>;
-    updateWorkspacePermissions: (workspaceId: string, permissions: Record<string, string[]>) => Promise<any>;
+    updateWorkspace: (ws: IWorkspace, data: Partial<IWorkspace>) => Promise<void>;
+    deleteWorkspace: (workspaceId: string) => Promise<unknown>;
     getWorkspace: (workspaceId: string) => Promise<IWorkspace>;
-    updateWorkspace: (ws: IWorkspace, _data: Partial<IWorkspace>) => Promise<void>;
     getUsers: (workspaceId: string) => Promise<IWorkspaceUser[]>;
     addUser: (workspaceId: string, email: string, role: string) => Promise<{
         userId: string;
-        workspace: IWorkspace;
-        message: string;
     }>;
     removeUser: (workspaceId: string, userId: string) => Promise<{
         userId: string;
-        workspace: IWorkspace;
-        message: string;
     }>;
     updateUser: (workspaceId: string, userId: string, config: Partial<IWorkspaceUser>) => Promise<{
         userId: string;
@@ -4509,9 +4818,18 @@ declare const useSaaSWorkspaces: () => {
     }>;
     getProfile: () => Promise<IUser>;
     updateUserProfile: (config: Partial<IUser>) => Promise<IUser>;
-    deleteWorkspace: (workspaceId: string) => Promise<{
-        success: boolean;
-    }>;
+    getFeatures: () => Promise<IWorkspaceFeature[] | null>;
+    updateFeature: (workspaceId: string, key: string, value: boolean) => Promise<IWorkspace>;
+    updateWorkspaceSettings: (data: {
+        permissions: Record<string, string[]>;
+    }) => Promise<unknown>;
+    updateWorkspacePermissions: (workspaceId: string, permissions: Record<string, string[]>) => Promise<unknown>;
+    workspaces: IWorkspace[];
+    loading: boolean;
+    error: string | null;
+    refreshing: boolean;
+    currentWorkspace: IWorkspace | null;
+    allFeatures: IWorkspaceFeature[];
     switching: boolean;
     switchingToId: string | null;
 };
@@ -5702,7 +6020,7 @@ declare function EmptyState({ icon, title, description, action, className }: Emp
 interface FullScreenLoaderProps {
     /** Content to display centered on screen. Falls back to a default spinner + message. */
     children?: React__default.ReactNode;
-    /** Message shown below the default spinner (only used when no children are provided). Defaults to "Loading..." */
+    /** Message shown below the default spinner (only used when no children are provided). Defaults to the translated "Loading..." */
     message?: string;
     /** Background color of the overlay. Defaults to white (dark mode: near-black). */
     backgroundColor?: string;
@@ -5726,7 +6044,7 @@ interface FullScreenLoaderProps {
  * ```
  */
 declare const FullScreenLoader: {
-    ({ children, message, backgroundColor, }: FullScreenLoaderProps): react_jsx_runtime.JSX.Element;
+    ({ children, message: messageProp, backgroundColor, }: FullScreenLoaderProps): react_jsx_runtime.JSX.Element;
     displayName: string;
 };
 
@@ -5915,5 +6233,5 @@ declare class WorkspaceSettingsManager {
 }
 declare const workspaceSettingsManager: WorkspaceSettingsManager;
 
-export { ApiVersion, AuthApi, AuthStatus, BBAction, BBScreen, BBStatus, BB_PARAM, BaseApi, BetaForm, BillingIntervals, CURRENCY_DISPLAY, CURRENCY_FLAG, ConnectedAgents, ConnectedAgentsApi, CreditActionsProvider, CreditBalance, CreditBalanceContextProvider, CreditBucketSource, CreditBucketStatus, CreditStorePage, CreditTransactionType, DEFAULT_ROLE_PERMISSIONS, DunningState, EmptyState, EventEmitter, FullScreenLoader, InvoiceStatuses, LoadingState, PLAN_CURRENCY_CODES, PLAN_CURRENCY_OPTIONS, PUSH_SERVICE_WORKER_SCRIPT, Permission, PricingPage, PushApi, PushNotificationProvider, QuotaUsageContextProvider, SDKEvent, SETTINGS_SCREENS, SUPPORTED_LOCALES, SaaSOSProvider, SectionHeader, SettingsApi, SettingsScreen, SidebarNavItem, SidebarNavSection, StatusBanner, SubscriptionContextProvider, SubscriptionItemType, SubscriptionStatus, UserApi, WhenAuthenticated, WhenCreditsAvailable, WhenCreditsExhausted, WhenCreditsLow, WhenNoSubscription, WhenNotTrialing, WhenPermission, WhenQuotaAvailable, WhenQuotaExhausted, WhenQuotaOverage, WhenQuotaThreshold, WhenRoles, WhenSubscription, WhenSubscriptionToPlans, WhenTrialEnding, WhenTrialing, WhenUnauthenticated, WhenUserFeatureDisabled, WhenUserFeatureEnabled, WhenWorkspaceFeatureDisabled, WhenWorkspaceFeatureEnabled, WhenWorkspaceRoles, WorkspaceApi, WorkspaceSwitcher, calculateBillableSeats, calculateSeatOverageCents, calculateTotalSubscriptionCents, cleanBBParams, clearAuthIntent, consumeAuthIntent, createBBUrl, createCheckoutRedirectUrls, createCreditPurchaseRedirectUrls, eventEmitter, formatCents, formatOverageRate, formatOverageRateWithLabel, formatQuotaIncludedOverage, formatQuotaWithPrice, getAvailableCurrenciesFromPlans, getBasePriceCents, getBillingIntervalAndCurrencyFromPriceId, getCurrencyFlag, getCurrencySymbol, getDisplayCurrency, getPerSeatPriceCents, getPricingVariant, getQuotaDisplayValue, getQuotaDisplayWithVariant, getQuotaOverageCents, getQuotaUnitLabelFromName, getSeatPricing, getStripePriceIdForInterval, hasPermission, invalidateCreditBalance, invalidateQuotaUsage, invalidateSubscription, isZeroDecimalCurrency, mergeUIConfig, minorAmountToDisplay, readBBParams, resolveMaxUsers, resolvePermissions, safeRedirect, saveAuthIntent, useAllQuotaUsage, useBillingPortal, useCancelSubscription, useConnectedAgents, useConnectedAgentsApi, useConsumeCredits, useCreateCheckoutSession, useCreditBalance, useCreditBalanceContext, useCreditPackages, useCreditTransactions, useExpiringCredits, useFullScreenLoader, useInvoice, useInvoices, usePermissions, usePlanGroup, usePlanGroupVersions, usePublicCreditPackages, usePublicPlanGroupVersion, usePublicPlans, usePurchaseCredits, usePushNotifications, useQuotaUsageContext, useQuotaUsageStatus, useRecordUsage, useResumeSubscription, useSaaSAuth, useSaaSOs, useSaaSSettings, useSaaSWorkspaces, useSeatStatus, useSubscription, useSubscriptionContext, useSubscriptionManagement, useTranslation, useTrialStatus, useUIConfig, useUIVisibility, useUpdateSubscription, useUsageLogs, useUserAttributes, useUserFeatures, validateInvite, validateRedirectUrl, workspaceSettingsManager };
-export type { BBActionType, BBScreenType, BBStatusType, BetaFormData, BetaFormResponse, BillingInterval, CheckoutResult, ConnectedAgentsProps, CreditActionsDetails, CreditBalanceContextValue, CreditBalanceDetails, CreditBucketSourceType, CreditBucketStatusType, CreditStorePageDetails, CreditTransactionTypeValue, DunningStateType, EmptyStateProps, EventData, EventType, FormatQuotaWithPriceOptions, FullScreenLoaderProps, GetCheckoutStripeParams, IAllQuotaUsageResponse, IBaseApiConfig, IBasePricing, IBetaConfig, ICheckoutSessionRequest, ICheckoutSessionResponse, ICheckoutStripeOptions, IConnectedAgent, IConsumeCreditsRequest, IConsumeCreditsResponse, ICreditBalance, ICreditBucket, ICreditBucketsQuery, ICreditBucketsResponse, ICreditPackage, ICreditPackagePricingVariant, ICreditPurchaseRequest, ICreditPurchaseResponse, ICreditTransaction, ICreditTransactionsQuery, ICreditTransactionsResponse, IEventCallbacks, IExpiringCreditsResponse, IInvoice, IInvoiceListResponse, IInvoiceResponse, IOsConfig, IOsState, IPlan, IPlanGroup, IPlanGroupInfo, IPlanGroupLatestVersion, IPlanGroupResponse, IPlanGroupVersion, IPlanGroupVersionWithPlans, IPlanGroupVersionsResponse, IPlanVersion, IPlanVersionSummary, IPlanVersionWithPlan, IPricingVariant, IPublicCreditPackage, IPublicCreditPackagesResponse, IPublicPlanItem, IPublicPlanItemCategory, IPublicPlanVersion, IPublicPlansResponse, IQuotaByInterval, IQuotaIntervalValue, IQuotaOveragePriceIdsByInterval, IQuotaOveragesByInterval, IQuotaUsageStatus, IQuotaUsageStatusResponse, IRecordUsageRequest, IRecordUsageResponse, ISettings, IStripePricesByInterval, ISubscription, ISubscriptionItem, ISubscriptionResponse, ISubscriptionUpdateRequest, ISubscriptionUpdateResponse, IUsageLogEntry, IUsageLogsQuery, IUsageLogsResponse, IUser, IWorkspace, InviteBlockReason, InviteValidation, InvoiceStatus, InvoiceStatusType, LoadingProps, LoadingStateProps, MaxUsersConfig, NotificationData, NotificationEvent, NotificationResult, OnWorkspaceChangeParams, PartialSDKMessages, PermissionContext, PermissionKey, PlanVersionWithPricingVariants, PricingPageDetails, PricingPageProps, QuotaDisplayValue, QuotaDisplayWithOverage, QuotaUsageContextValue, RedirectValidationOptions, RolePermissionMap, SDKLocale, SDKMessages, SDKUIConfig, SaaSOSProviderProps, SeatStatus, SectionHeaderProps, SettingsManagerState, SidebarNavItemProps, SidebarNavSectionProps, StatusBannerProps, StatusBannerVariant, SubscriptionContextValue, SubscriptionItemTypeValue, SubscriptionStatusType, TranslationKey, TrialStatus, UseConnectedAgents, UserCreatedEventData, UserUpdatedEventData, WorkspaceChangedEventData, WorkspaceCreatedEventData, WorkspaceDeletedEventData, WorkspaceSettingsSection, WorkspaceUpdatedEventData, WorkspaceUserAddedEventData, WorkspaceUserRemovedEventData, WorkspaceUserRoleChangedEventData };
+export { ApiVersion, AuthApi, AuthStatus, BBAction, BBScreen, BBStatus, BB_PARAM, BaseApi, BetaForm, BillingIntervals, SaaSOSProvider as BuildBaseProvider, CURRENCY_DISPLAY, CURRENCY_FLAG, ConnectMcpGuide, ConnectedAgents, ConnectedAgentsApi, CreditActionsProvider, CreditBalance, CreditBalanceContextProvider, CreditBucketSource, CreditBucketStatus, CreditStorePage, CreditTransactionType, DEFAULT_ROLE_PERMISSIONS, DunningState, EmptyState, EventEmitter, FullScreenLoader, InvoiceStatuses, LoadingState, PLAN_CURRENCY_CODES, PLAN_CURRENCY_OPTIONS, PUSH_SERVICE_WORKER_SCRIPT, Permission, PricingPage, PushApi, PushNotificationProvider, QuotaUsageContextProvider, SDKEvent, SETTINGS_SCREENS, SUPPORTED_LOCALES, SaaSOSProvider, SectionHeader, SettingsApi, SettingsScreen, SidebarNavItem, SidebarNavSection, StatusBanner, SubscriptionContextProvider, SubscriptionItemType, SubscriptionStatus, UserApi, WhenAuthenticated, WhenCreditsAvailable, WhenCreditsExhausted, WhenCreditsLow, WhenNoSubscription, WhenNotTrialing, WhenPermission, WhenQuotaAvailable, WhenQuotaExhausted, WhenQuotaOverage, WhenQuotaThreshold, WhenRoles, WhenSubscription, WhenSubscriptionToPlans, WhenTrialEnding, WhenTrialing, WhenUnauthenticated, WhenUserFeatureDisabled, WhenUserFeatureEnabled, WhenWorkspaceFeatureDisabled, WhenWorkspaceFeatureEnabled, WhenWorkspaceRoles, WorkspaceApi, WorkspaceSwitcher, calculateBillableSeats, calculateSeatOverageCents, calculateTotalSubscriptionCents, cleanBBParams, clearAuthIntent, consumeAuthIntent, createBBUrl, createCheckoutRedirectUrls, createCreditPurchaseRedirectUrls, eventEmitter, fillMcpTemplate, formatCents, formatMinorAmountIntl, formatOverageRate, formatOverageRateWithLabel, formatQuotaIncludedOverage, formatQuotaWithPrice, getAvailableCurrenciesFromPlans, getBasePriceCents, getBillingIntervalAndCurrencyFromPriceId, getCurrencyDecimals, getCurrencyFlag, getCurrencySymbol, getDisplayCurrency, getPerSeatPriceCents, getPricingVariant, getQuotaDisplayValue, getQuotaDisplayWithVariant, getQuotaOverageCents, getQuotaUnitLabelFromName, getSeatPricing, getStripePriceIdForInterval, hasPermission, invalidateCreditBalance, invalidateQuotaUsage, invalidateSubscription, isZeroDecimalCurrency, mcpServerKey, mergeUIConfig, minorAmountToDisplay, readBBParams, resolveMaxUsers, resolvePermissions, safeRedirect, saveAuthIntent, useAllQuotaUsage, useBillingPortal, useCancelSubscription, useConnectedAgents, useConnectedAgentsApi, useConsumeCredits, useCreateCheckoutSession, useCreditBalance, useCreditBalanceContext, useCreditPackages, useCreditTransactions, useExpiringCredits, useFullScreenLoader, useInvoice, useInvoices, useMcpConnection, usePermissions, usePlanGroup, usePlanGroupVersions, usePublicCreditPackages, usePublicPlanGroupVersion, usePublicPlans, usePurchaseCredits, usePushNotifications, useQuotaUsageContext, useQuotaUsageStatus, useRecordUsage, useResumeSubscription, useSaaSAuth, useSaaSOs, useSaaSSettings, useSaaSWorkspaces, useSeatStatus, useSubscription, useSubscriptionContext, useSubscriptionManagement, useTranslation, useTrialStatus, useUIConfig, useUIVisibility, useUpdateSubscription, useUsageLogs, useUserAttributes, useUserFeatures, validateInvite, validateRedirectUrl, workspaceSettingsManager };
+export type { BBActionType, BBScreenType, BBStatusType, BetaFormData, BetaFormResponse, BillingInterval, SaaSOSProviderProps as BuildBaseProviderProps, CheckoutResult, ConnectMcpGuideProps, ConnectedAgentsProps, CreditActionsDetails, CreditBalanceContextValue, CreditBalanceDetails, CreditBucketSourceType, CreditBucketStatusType, CreditStorePageDetails, CreditTransactionTypeValue, DunningStateType, EmptyStateProps, EventData, EventType, FormatQuotaWithPriceOptions, FullScreenLoaderProps, GetCheckoutStripeParams, IAllQuotaUsageResponse, IBaseApiConfig, IBasePricing, IBetaConfig, ICheckoutSessionRequest, ICheckoutSessionResponse, ICheckoutStripeOptions, IConnectedAgent, IConsumeCreditsRequest, IConsumeCreditsResponse, ICreditBalance, ICreditBucket, ICreditBucketsQuery, ICreditBucketsResponse, ICreditPackage, ICreditPackagePricingVariant, ICreditPurchaseRequest, ICreditPurchaseResponse, ICreditTransaction, ICreditTransactionsQuery, ICreditTransactionsResponse, IEventCallbacks, IExpiringCreditsResponse, IInvoice, IInvoiceListResponse, IInvoiceResponse, IOsConfig, IOsState, IPlan, IPlanGroup, IPlanGroupInfo, IPlanGroupLatestVersion, IPlanGroupResponse, IPlanGroupVersion, IPlanGroupVersionWithPlans, IPlanGroupVersionsResponse, IPlanVersion, IPlanVersionSummary, IPlanVersionWithPlan, IPricingVariant, IPublicCreditPackage, IPublicCreditPackagesResponse, IPublicPlanItem, IPublicPlanItemCategory, IPublicPlanVersion, IPublicPlansResponse, IQuotaByInterval, IQuotaIntervalValue, IQuotaOveragePriceIdsByInterval, IQuotaOveragesByInterval, IQuotaUsageStatus, IQuotaUsageStatusResponse, IRecordUsageRequest, IRecordUsageResponse, ISettings, IStripePricesByInterval, ISubscription, ISubscriptionItem, ISubscriptionResponse, ISubscriptionUpdateRequest, ISubscriptionUpdateResponse, IUsageLogEntry, IUsageLogsQuery, IUsageLogsResponse, IUser, IWorkspace, InviteBlockReason, InviteValidation, InvoiceStatus, InvoiceStatusType, LoadingProps, LoadingStateProps, MaxUsersConfig, McpClientGuide, McpConnectionConfig, NotificationData, NotificationEvent, NotificationResult, OnWorkspaceChangeParams, PartialSDKMessages, PermissionContext, PermissionKey, PlanVersionWithPricingVariants, PricingPageDetails, PricingPageProps, QuotaDisplayValue, QuotaDisplayWithOverage, QuotaUsageContextValue, RedirectValidationOptions, RolePermissionMap, SDKLocale, SDKMessages, SDKUIConfig, SaaSOSProviderProps, SeatStatus, SectionHeaderProps, SettingsManagerState, SidebarNavItemProps, SidebarNavSectionProps, StatusBannerProps, StatusBannerVariant, SubscriptionContextValue, SubscriptionItemTypeValue, SubscriptionStatusType, TranslationKey, TrialStatus, UseConnectedAgents, UserCreatedEventData, UserUpdatedEventData, WorkspaceChangedEventData, WorkspaceCreatedEventData, WorkspaceDeletedEventData, WorkspaceSettingsSection, WorkspaceUpdatedEventData, WorkspaceUserAddedEventData, WorkspaceUserRemovedEventData, WorkspaceUserRoleChangedEventData };