@buildbase/sdk 0.0.49 → 0.0.51

package/dist/react/index.d.ts

@@ -1,5 +1,5 @@
-import * as react from 'react';
-import react__default, { ReactNode } from 'react';
+import * as React$1 from 'react';
+import React__default, { ReactNode } from 'react';
 import * as react_jsx_runtime from 'react/jsx-runtime';
 
 interface IDocument {
@@ -1148,6 +1148,15 @@ declare abstract class BaseApi {
      * Tries to parse JSON error body; falls back to status-based message.
      */
     protected throwResponseError(response: Response, defaultMsg: string): Promise<never>;
+    /**
+     * Tagged template that URI-encodes interpolated path segments, so IDs
+     * containing `/ ? # ..` can't retarget the request path.
+     * Use for PATH segments only — never for pre-built query strings.
+     *
+     * @example
+     * this.apiPath`workspaces/${workspaceId}/users/${userId}`
+     */
+    protected apiPath(strings: TemplateStringsArray, ...values: Array<string | number>): string;
     /**
      * Parse JSON and unwrap `{ success, data }` envelope if present.
      * Throws if `success` is explicitly `false`.
@@ -1209,6 +1218,33 @@ interface IBetaConfig extends IDocument {
     };
 }
 
+/**
+ * API client for the signed-in user's "connected agents" — the AI agents they
+ * have authorized to access their account. Session-authed (x-session-id),
+ * scoped to the current user. Extends BaseApi for shared URL/auth/request handling.
+ */
+
+/** An agent the user has connected to their account. */
+interface IConnectedAgent {
+    /** OAuth client id of the connected agent. */
+    clientId: string;
+    /** Display name of the agent. */
+    title: string;
+    /** Scopes the user granted it. */
+    scope: string[];
+    /** When the grant was last (re)approved (ISO string). */
+    lastGrantedAt?: string;
+}
+declare class ConnectedAgentsApi extends BaseApi {
+    constructor(config: Pick<IOsConfig, 'serverUrl' | 'version'> & {
+        sessionId?: string;
+    });
+    /** List the agents the current user has connected. */
+    list(signal?: AbortSignal): Promise<IConnectedAgent[]>;
+    /** Disconnect one agent from the current user's account. */
+    revoke(clientId: string): Promise<void>;
+}
+
 declare class PushApi extends BaseApi {
     constructor(config: Pick<IBaseApiConfig, 'serverUrl' | 'version' | 'orgId' | 'sessionId'>);
     getVapidPublicKey(): Promise<{
@@ -1842,8 +1878,14 @@ declare function validateRedirectUrl(url: string | null | undefined): string | n
 /**
  * Safely redirect to a URL after validating it.
  * Falls back to fallbackUrl if the target URL is invalid.
+ *
+ * Browser-only: navigation requires `window.location`. On non-browser runtimes
+ * (Node, edge, Deno, Bun) there is nothing to navigate, so this is a no-op that
+ * returns `false`. Returns `true` when a navigation was initiated. Server code
+ * that needs the resolved target should call {@link validateRedirectUrl} and
+ * issue the redirect with its own framework (e.g. `Response.redirect`).
  */
-declare function safeRedirect(url: string | null | undefined, fallbackUrl?: string): void;
+declare function safeRedirect(url: string | null | undefined, fallbackUrl?: string): boolean;
 
 /**
  * Auth intent preservation — saves and restores the URL the user was on
@@ -2224,6 +2266,12 @@ declare function useFullScreenLoader(): FullScreenLoaderContextValue;
  */
 interface SDKMessages {
     security: {
+        connectedAgentsTitle: string;
+        connectedAgentsDescription: string;
+        connectedAgentsDisconnect: string;
+        connectedAgentsEmpty: string;
+        connectedAgentsAccess: string;
+        connectedAgentsGranted: string;
         inactive: string;
         inactiveHint: string;
         passkeysTitle: string;
@@ -2285,6 +2333,8 @@ interface SDKMessages {
             noPermissionTitle: string;
             noPermissionDescription: string;
             billingManageOnly: string;
+            openSettings: string;
+            back: string;
         };
     };
     subscription: {
@@ -2728,6 +2778,7 @@ interface SDKMessages {
         searchCurrency: string;
         chooseTimezone: string;
         searchTimezone: string;
+        noResults: string;
     };
     push: {
         failedToSubscribe: string;
@@ -2823,9 +2874,19 @@ interface SDKMessages {
 }
 /** Supported locale codes */
 type SDKLocale = 'en' | 'es' | 'fr' | 'de' | 'ja' | 'zh' | 'hi' | 'ar';
+/** Recursively optional version of a message tree (leaves stay strings) */
+type DeepPartialMessages<T> = {
+    [K in keyof T]?: T[K] extends string ? string : DeepPartialMessages<T[K]>;
+};
+/**
+ * Per-key overrides for SDK UI strings — any subset of the SDKMessages tree.
+ * Deep-merged over the active locale bundle by the translation provider.
+ */
+type PartialSDKMessages = DeepPartialMessages<SDKMessages>;
 /**
  * Generates a union of all valid dot-separated key paths from SDKMessages.
- * Supports up to 3 levels of nesting (covers all current keys).
+ * Supports up to 4 levels of nesting (covers all current keys, e.g.
+ * "notifications.unblock.firefox.step1").
  * Used to make `t()` calls compile-time safe with autocomplete.
  *
  * @example
@@ -2850,6 +2911,156 @@ type Level4 = {
 /** Union of all valid translation key paths (e.g. "settings.titles.profile") */
 type TranslationKey = Level2 | Level3 | Level4;
 
+/**
+ * Settings screen identifiers — kept in a leaf module (no component imports)
+ * so consumers of `SettingsScreen` don't pull the whole settings dialog
+ * (and its 12 screens) into their bundle. The dialog itself is lazy-loaded.
+ */
+declare const SettingsScreen: {
+    readonly Profile: "profile";
+    readonly Security: "security";
+    readonly ConnectedAgents: "connected-agents";
+    readonly General: "general";
+    readonly Users: "users";
+    readonly Subscription: "subscription";
+    readonly Usage: "usage";
+    readonly Credits: "credits";
+    readonly Features: "features";
+    readonly Notifications: "notifications";
+    readonly Permissions: "permissions";
+    readonly Danger: "danger";
+};
+type WorkspaceSettingsSection = (typeof SettingsScreen)[keyof typeof SettingsScreen];
+/** Set of all valid section values — used for runtime validation */
+declare const SETTINGS_SCREENS: Set<WorkspaceSettingsSection>;
+
+/**
+ * Implementor-facing UI configuration for the SDK.
+ *
+ * Every option is additive and defaults to the current behavior, so the
+ * config is never required. Visibility options can only HIDE UI — they
+ * never bypass platform permissions, which remain the security floor.
+ */
+interface SDKUIConfig {
+    /** Workspace settings dialog. */
+    settings?: {
+        /**
+         * Show/hide sidebar sections of the workspace settings dialog.
+         * Omitted sections stay visible. Hiding a section also prevents its
+         * screen from rendering via deep links or `defaultSection`.
+         *
+         * @example
+         * ```tsx
+         * ui={{ settings: { sections: { credits: false, 'connected-agents': false } } }}
+         * ```
+         */
+        sections?: Partial<Record<WorkspaceSettingsSection, boolean>>;
+        /** Profile screen — hide individual preference fields. */
+        profile?: {
+            language?: boolean;
+            country?: boolean;
+            currency?: boolean;
+            timezone?: boolean;
+        };
+        /** Security screen — hide passkey row actions. */
+        security?: {
+            passkeyRename?: boolean;
+            passkeyDelete?: boolean;
+        };
+        /** General screen — hide workspace editing affordances. */
+        general?: {
+            nameEdit?: boolean;
+            iconEditor?: boolean;
+        };
+        /** Users screen — hide member-management affordances. */
+        users?: {
+            invite?: boolean;
+            roleChange?: boolean;
+            remove?: boolean;
+            /** Seat usage / seat pricing block above the member list. */
+            seatPricing?: boolean;
+        };
+        /** Subscription screen — hide billing actions. */
+        subscription?: {
+            changePlan?: boolean;
+            cancel?: boolean;
+            managePayment?: boolean;
+            invoicesTab?: boolean;
+            /** Expandable plan features/limits/quotas breakdown. */
+            planDetails?: boolean;
+        };
+        /** Credits screen — hide purchase/history blocks. */
+        credits?: {
+            buyButton?: boolean;
+            transactions?: boolean;
+        };
+        /** Notifications screen — hide the push block or preference columns. */
+        notifications?: {
+            /** Browser push-notification block (subscribe/unsubscribe). */
+            push?: boolean;
+            /** Per-event email preference column. */
+            emailToggles?: boolean;
+            /** Per-event push preference column. */
+            pushToggles?: boolean;
+        };
+    };
+    /** Workspace switcher dialog (client-side; ANDed with server settings). */
+    workspaceSwitcher?: {
+        /** Overrides `settings.workspace.showSwitcher` to hide the switcher UI. */
+        show?: boolean;
+        createButton?: boolean;
+        /** Subscription plan badge on each workspace row. */
+        planBadge?: boolean;
+        memberCount?: boolean;
+    };
+    /** SDK behaviors that are currently automatic. */
+    behavior?: {
+        /**
+         * Auto-open the plan picker dialog when a workspace has no
+         * subscription. Default true (current behavior).
+         */
+        autoOpenPlanDialog?: boolean;
+        /** Default `daysThreshold` for `WhenTrialEnding` (default 3). */
+        trialEndingDays?: number;
+    };
+    /**
+     * Per-key overrides for SDK UI strings, deep-merged over the active
+     * locale bundle. Use to rebrand terms (e.g. "Credits" → "Tokens")
+     * without forking locale files.
+     *
+     * @example
+     * ```tsx
+     * ui={{ messages: { settings: { sidebar: { credits: 'Tokens' } } } }}
+     * ```
+     */
+    messages?: PartialSDKMessages;
+    /**
+     * Strings for the top-level error boundary's default fallback.
+     * Plain strings (not i18n keys) — the boundary renders even when the
+     * translation layer itself has crashed.
+     */
+    errorBoundary?: {
+        title?: string;
+        retryLabel?: string;
+    };
+    /** Locale-aware formatting defaults. */
+    formats?: {
+        /**
+         * Options for dates the SDK renders (passkey activity, connected agents,
+         * etc.). Default: `{ dateStyle: 'medium' }`.
+         */
+        date?: Intl.DateTimeFormatOptions;
+    };
+}
+/** Access the implementor-provided UI config (empty object when unset). */
+declare function useUIConfig(): SDKUIConfig;
+/**
+ * Deep-merge a per-instance UI config over a base (provider-global) one.
+ * Instance leaves win; objects merge recursively. Used by components that
+ * accept their own `ui` prop (e.g. WorkspaceSettingsDialog).
+ */
+declare function mergeUIConfig(base: SDKUIConfig, override?: SDKUIConfig): SDKUIConfig;
+
 /** Values that can be interpolated into ICU messages */
 type TranslationValues = Record<string, string | number | boolean>;
 /** All supported locale codes */
@@ -2885,7 +3096,7 @@ declare function useTranslation(): {
 };
 
 interface SaaSOSProviderProps extends IOsState {
-    children: react__default.ReactNode;
+    children: React__default.ReactNode;
     /** SDK UI language. Defaults to 'en'. Supported: en, es, fr, de, ja, zh, hi, ar */
     locale?: SDKLocale;
     /**
@@ -2956,26 +3167,49 @@ interface SaaSOSProviderProps extends IOsState {
      * >
      * ```
      */
-    loadingComponent?: react__default.ReactNode | ((props: LoadingProps) => react__default.ReactNode);
+    loadingComponent?: React__default.ReactNode | ((props: LoadingProps) => React__default.ReactNode);
+    /**
+     * UI configuration — control which parts of the SDK UI are shown and
+     * override individual UI strings. Everything defaults to visible/current
+     * behavior; visibility options only hide UI and never bypass permissions.
+     *
+     * @example Hide settings sections and rebrand a label
+     * ```tsx
+     * <SaaSOSProvider
+     *   ui={{
+     *     settings: { sections: { credits: false, notifications: false } },
+     *     messages: { settings: { sidebar: { subscription: 'Billing' } } },
+     *   }}
+     * >
+     * ```
+     */
+    ui?: SDKUIConfig;
 }
-declare const SaaSOSProvider: react__default.FC<SaaSOSProviderProps>;
+declare const SaaSOSProvider: React__default.FC<SaaSOSProviderProps>;
 
 interface IProps$2 {
     children: React.ReactNode;
+    /** Optional component/element to show while auth status is still loading. */
+    loadingComponent?: React.ReactNode;
+    /** Optional component/element to show when the condition is not met. */
+    fallbackComponent?: React.ReactNode;
 }
 /**
  * Conditional component that renders children only when user is authenticated.
- * Returns null if user is not authenticated or authentication status is still loading.
+ * Optionally pass loadingComponent (while auth resolves) or fallbackComponent
+ * (when unauthenticated) — both default to null, matching the other SDK gates.
  *
  * @param props - Component props
  * @param props.children - Content to render when authenticated
+ * @param props.loadingComponent - Optional content while auth status resolves
+ * @param props.fallbackComponent - Optional content when not authenticated
  *
  * @example
  * ```tsx
  * function App() {
  *   return (
  *     <SaaSOSProvider {...config}>
- *       <WhenAuthenticated>
+ *       <WhenAuthenticated loadingComponent={<Skeleton />}>
  *         <Dashboard />
  *       </WhenAuthenticated>
  *       <WhenUnauthenticated>
@@ -2987,16 +3221,19 @@ interface IProps$2 {
  * ```
  */
 declare const WhenAuthenticated: {
-    (props: IProps$2): react.ReactNode;
+    (props: IProps$2): React$1.ReactNode;
     displayName: string;
 };
 /**
  * Conditional component that renders children only when user is NOT authenticated.
- * Returns null if user is authenticated.
- * Note: Also renders during loading/redirecting states (when not yet authenticated).
+ * Optionally pass loadingComponent (while auth resolves) or fallbackComponent
+ * (when authenticated) — both default to null, matching the other SDK gates.
+ * Note: without loadingComponent, nothing renders during loading/redirecting states.
  *
  * @param props - Component props
  * @param props.children - Content to render when unauthenticated
+ * @param props.loadingComponent - Optional content while auth status resolves
+ * @param props.fallbackComponent - Optional content when authenticated
  *
  * @example
  * ```tsx
@@ -3032,27 +3269,10 @@ declare const WhenAuthenticated: {
  * ```
  */
 declare const WhenUnauthenticated: {
-    (props: IProps$2): react.ReactNode;
+    (props: IProps$2): React$1.ReactNode;
     displayName: string;
 };
 
-declare const SettingsScreen: {
-    readonly Profile: "profile";
-    readonly Security: "security";
-    readonly General: "general";
-    readonly Users: "users";
-    readonly Subscription: "subscription";
-    readonly Usage: "usage";
-    readonly Credits: "credits";
-    readonly Features: "features";
-    readonly Notifications: "notifications";
-    readonly Permissions: "permissions";
-    readonly Danger: "danger";
-};
-type WorkspaceSettingsSection = (typeof SettingsScreen)[keyof typeof SettingsScreen];
-/** Set of all valid section values — used for runtime validation */
-declare const SETTINGS_SCREENS: Set<WorkspaceSettingsSection>;
-
 declare function useSaaSAuth(): {
     signIn: (returnUrl?: string) => Promise<void>;
     signOut: () => Promise<void>;
@@ -3108,7 +3328,7 @@ interface IProps$1 {
  * ```
  */
 declare const WhenRoles: {
-    (props: IProps$1): react.ReactNode;
+    (props: IProps$1): React$1.ReactNode;
     displayName: string;
 };
 /**
@@ -3147,7 +3367,7 @@ declare const WhenRoles: {
  * ```
  */
 declare const WhenWorkspaceRoles: {
-    (props: IProps$1): react.ReactNode;
+    (props: IProps$1): React$1.ReactNode;
     displayName: string;
 };
 
@@ -3178,7 +3398,7 @@ interface WhenPermissionProps {
  * ```
  */
 declare const WhenPermission: {
-    (props: WhenPermissionProps): react.ReactNode;
+    (props: WhenPermissionProps): React$1.ReactNode;
     displayName: string;
 };
 
@@ -3219,6 +3439,52 @@ declare function usePermissions(workspace?: WorkspaceLike | null): {
     role: string | null;
 };
 
+/** Memoized ConnectedAgentsApi instance. Recreates only when serverUrl/version change. */
+declare function useConnectedAgentsApi(): ConnectedAgentsApi;
+
+interface UseConnectedAgents {
+    /** The agents the current user has connected to their account. */
+    agents: IConnectedAgent[];
+    /** True while the initial list is loading. */
+    loading: boolean;
+    /** Error message from the last list/revoke, if any. */
+    error: string | null;
+    /** The clientId currently being disconnected, or null. */
+    revoking: string | null;
+    /** Re-fetch the list. */
+    refresh: () => Promise<void>;
+    /** Disconnect an agent, then optimistically drop it from the list. */
+    revoke: (clientId: string) => Promise<void>;
+}
+/**
+ * Headless data + actions for a "Connected agents" screen. Session-authed and
+ * scoped to the signed-in user. Wrap your UI around it, or use the ready-made
+ * `<ConnectedAgents />` component.
+ */
+declare function useConnectedAgents(): UseConnectedAgents;
+
+interface ConnectedAgentsProps {
+    /** Extra classes for the root element. */
+    className?: string;
+    /** Heading text. Defaults to the translated title; set to null to hide. */
+    title?: string | null;
+    /** Sub-heading under the title. Defaults to the translated description; set to null to hide. */
+    description?: string | null;
+    /** Label for the disconnect button. Defaults to the translated label. */
+    disconnectLabel?: string;
+    /** Text shown when the user has no connected agents. Defaults to the translated label. */
+    emptyLabel?: string;
+}
+/**
+ * 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>.
+ *
+ * For a fully custom UI, use the `useConnectedAgents()` hook instead.
+ */
+declare function ConnectedAgents({ className, title, description, disconnectLabel, emptyLabel, }: ConnectedAgentsProps): react_jsx_runtime.JSX.Element;
+
 interface IProps {
     slug: string;
     children: React.ReactNode;
@@ -3260,7 +3526,7 @@ interface IProps {
  * ```
  */
 declare const WhenWorkspaceFeatureEnabled: {
-    (props: IProps): react.ReactNode;
+    (props: IProps): React$1.ReactNode;
     displayName: string;
 };
 /**
@@ -3283,7 +3549,7 @@ declare const WhenWorkspaceFeatureEnabled: {
  * ```
  */
 declare const WhenWorkspaceFeatureDisabled: {
-    (props: IProps): react.ReactNode;
+    (props: IProps): React$1.ReactNode;
     displayName: string;
 };
 /**
@@ -3322,7 +3588,7 @@ declare const WhenWorkspaceFeatureDisabled: {
  * ```
  */
 declare const WhenUserFeatureEnabled: {
-    (props: IProps): react.ReactNode;
+    (props: IProps): React$1.ReactNode;
     displayName: string;
 };
 /**
@@ -3345,7 +3611,7 @@ declare const WhenUserFeatureEnabled: {
  * ```
  */
 declare const WhenUserFeatureDisabled: {
-    (props: IProps): react.ReactNode;
+    (props: IProps): React$1.ReactNode;
     displayName: string;
 };
 
@@ -3386,7 +3652,7 @@ interface IWhenSubscriptionProps {
  * ```
  */
 declare const WhenSubscription: {
-    (props: IWhenSubscriptionProps): react.ReactNode;
+    (props: IWhenSubscriptionProps): React$1.ReactNode;
     displayName: string;
 };
 /**
@@ -3418,7 +3684,7 @@ declare const WhenSubscription: {
  * ```
  */
 declare const WhenNoSubscription: {
-    (props: IWhenSubscriptionProps): react.ReactNode;
+    (props: IWhenSubscriptionProps): React$1.ReactNode;
     displayName: string;
 };
 interface IWhenSubscriptionToPlansProps {
@@ -3462,7 +3728,7 @@ interface IWhenSubscriptionToPlansProps {
  * ```
  */
 declare const WhenSubscriptionToPlans: {
-    (props: IWhenSubscriptionToPlansProps): react.ReactNode;
+    (props: IWhenSubscriptionToPlansProps): React$1.ReactNode;
     displayName: string;
 };
 interface IWhenTrialingProps {
@@ -3485,7 +3751,7 @@ interface IWhenTrialingProps {
  * ```
  */
 declare const WhenTrialing: {
-    (props: IWhenTrialingProps): react.ReactNode;
+    (props: IWhenTrialingProps): React$1.ReactNode;
     displayName: string;
 };
 /**
@@ -3501,7 +3767,7 @@ declare const WhenTrialing: {
  * ```
  */
 declare const WhenNotTrialing: {
-    (props: IWhenTrialingProps): react.ReactNode;
+    (props: IWhenTrialingProps): React$1.ReactNode;
     displayName: string;
 };
 interface IWhenTrialEndingProps {
@@ -3511,12 +3777,16 @@ interface IWhenTrialEndingProps {
     loadingComponent?: React.ReactNode;
     /** Optional component/element to show when trial is not ending soon. */
     fallbackComponent?: React.ReactNode;
-    /** Number of days threshold to consider "ending soon". Defaults to 3. */
+    /**
+     * Number of days threshold to consider "ending soon".
+     * Defaults to `ui.behavior.trialEndingDays` from SaaSOSProvider, or 3.
+     */
     daysThreshold?: number;
 }
 /**
  * Renders children only when the subscription is trialing AND the trial ends within
- * the given threshold (default 3 days). Useful for showing urgent upgrade prompts.
+ * the given threshold (default 3 days, configurable globally via
+ * `ui.behavior.trialEndingDays`). Useful for showing urgent upgrade prompts.
  * Must be used within SubscriptionContextProvider.
  *
  * @example
@@ -3527,7 +3797,7 @@ interface IWhenTrialEndingProps {
  * ```
  */
 declare const WhenTrialEnding: {
-    (props: IWhenTrialEndingProps): react.ReactNode;
+    (props: IWhenTrialEndingProps): React$1.ReactNode;
     displayName: string;
 };
 
@@ -3568,7 +3838,7 @@ interface IWhenQuotaThresholdProps extends IWhenQuotaProps {
  * ```
  */
 declare const WhenQuotaAvailable: {
-    (props: IWhenQuotaProps): react.ReactNode;
+    (props: IWhenQuotaProps): React$1.ReactNode;
     displayName: string;
 };
 /**
@@ -3594,7 +3864,7 @@ declare const WhenQuotaAvailable: {
  * ```
  */
 declare const WhenQuotaExhausted: {
-    (props: IWhenQuotaProps): react.ReactNode;
+    (props: IWhenQuotaProps): React$1.ReactNode;
     displayName: string;
 };
 /**
@@ -3620,7 +3890,7 @@ declare const WhenQuotaExhausted: {
  * ```
  */
 declare const WhenQuotaOverage: {
-    (props: IWhenQuotaProps): react.ReactNode;
+    (props: IWhenQuotaProps): React$1.ReactNode;
     displayName: string;
 };
 /**
@@ -3648,7 +3918,7 @@ declare const WhenQuotaOverage: {
  * ```
  */
 declare const WhenQuotaThreshold: {
-    (props: IWhenQuotaThresholdProps): react.ReactNode;
+    (props: IWhenQuotaThresholdProps): React$1.ReactNode;
     displayName: string;
 };
 
@@ -3725,7 +3995,7 @@ interface CreditActionsProviderProps {
  * ```
  */
 declare const CreditActionsProvider: {
-    ({ children }: CreditActionsProviderProps): react.ReactNode;
+    ({ children }: CreditActionsProviderProps): React$1.ReactNode;
     displayName: string;
 };
 
@@ -3771,7 +4041,7 @@ interface CreditBalanceProps {
  * ```
  */
 declare const CreditBalance: {
-    ({ children }: CreditBalanceProps): react.ReactNode;
+    ({ children }: CreditBalanceProps): React$1.ReactNode;
     displayName: string;
 };
 
@@ -3883,7 +4153,7 @@ interface IWhenCreditsLowProps extends IWhenCreditsProps {
  * ```
  */
 declare const WhenCreditsAvailable: {
-    (props: IWhenCreditsAvailableProps): react.ReactNode;
+    (props: IWhenCreditsAvailableProps): React$1.ReactNode;
     displayName: string;
 };
 /**
@@ -3908,7 +4178,7 @@ declare const WhenCreditsAvailable: {
  * ```
  */
 declare const WhenCreditsExhausted: {
-    (props: IWhenCreditsProps): react.ReactNode;
+    (props: IWhenCreditsProps): React$1.ReactNode;
     displayName: string;
 };
 /**
@@ -3934,7 +4204,7 @@ declare const WhenCreditsExhausted: {
  * ```
  */
 declare const WhenCreditsLow: {
-    (props: IWhenCreditsLowProps): react.ReactNode;
+    (props: IWhenCreditsLowProps): React$1.ReactNode;
     displayName: string;
 };
 
@@ -3962,7 +4232,7 @@ interface SubscriptionContextValue {
  * @param props.children - React tree that may use subscription gates or useSubscriptionContext
  * @returns Provider element that supplies subscription context to descendants
  */
-declare const SubscriptionContextProvider: react__default.FC<{
+declare const SubscriptionContextProvider: React__default.FC<{
     children: ReactNode;
 }>;
 /**
@@ -3997,7 +4267,7 @@ interface QuotaUsageContextValue {
  * @param props.children - React tree that may use quota gates or useQuotaUsageContext
  * @returns Provider element that supplies quota usage context to descendants
  */
-declare const QuotaUsageContextProvider: react__default.FC<{
+declare const QuotaUsageContextProvider: React__default.FC<{
     children: ReactNode;
 }>;
 /**
@@ -4025,7 +4295,7 @@ interface CreditBalanceContextValue {
  * (e.g. after consume or purchase).
  * Included in SaaSOSProvider by default.
  */
-declare const CreditBalanceContextProvider: react__default.FC<{
+declare const CreditBalanceContextProvider: React__default.FC<{
     children: ReactNode;
 }>;
 /**
@@ -5286,7 +5556,7 @@ interface BetaFormProps {
     hideLogo?: boolean;
     hideTitles?: boolean;
 }
-declare const BetaForm: react__default.FC<BetaFormProps>;
+declare const BetaForm: React__default.FC<BetaFormProps>;
 
 interface PricingPageDetails {
     /** Whether plan data is being fetched */
@@ -5358,9 +5628,27 @@ interface PricingPageProps {
  */
 declare function PricingPage({ slug, children, loadingFallback, errorFallback, redirectBaseUrl, }: PricingPageProps): react_jsx_runtime.JSX.Element;
 
+interface EmptyStateProps {
+    /** Icon shown above the text, e.g. `<KeyRound className="h-5 w-5 text-muted-foreground" />` */
+    icon?: React$1.ReactNode;
+    /** Short headline. Optional — many empty states only need a description. */
+    title?: string;
+    /** Muted explanatory text. */
+    description?: string;
+    /** Optional call-to-action rendered under the text (e.g. a Button). */
+    action?: React$1.ReactNode;
+    className?: string;
+}
+/**
+ * Standard empty-list placeholder: dashed border card with a centered icon,
+ * muted text and an optional action. Use for every "nothing here yet" state
+ * so all screens share the same look.
+ */
+declare function EmptyState({ icon, title, description, action, className }: EmptyStateProps): react_jsx_runtime.JSX.Element;
+
 interface FullScreenLoaderProps {
     /** Content to display centered on screen. Falls back to a default spinner + message. */
-    children?: react__default.ReactNode;
+    children?: React__default.ReactNode;
     /** Message shown below the default spinner (only used when no children are provided). Defaults to "Loading..." */
     message?: string;
     /** Background color of the overlay. Defaults to white (dark mode: near-black). */
@@ -5389,6 +5677,84 @@ declare const FullScreenLoader: {
     displayName: string;
 };
 
+interface LoadingStateProps {
+    /** Text next to the spinner. Defaults to the translated "Loading…". */
+    label?: string;
+    className?: string;
+}
+/**
+ * Standard inline loading box: gray bordered bar with a spinner and label.
+ * Use for in-place refreshes where a skeleton would be too heavy;
+ * use `Skeleton`/`SettingSkeleton` for initial screen loads.
+ */
+declare function LoadingState({ label, className }: LoadingStateProps): react_jsx_runtime.JSX.Element;
+
+interface SectionHeaderProps {
+    /** Section title. Pass null to hide (e.g. when a parent already renders it). */
+    title?: string | null;
+    /** Muted description under the title. */
+    description?: string | null;
+    /** Optional element aligned to the end of the title row (e.g. a badge or button). */
+    actions?: React$1.ReactNode;
+    className?: string;
+    /** Extra classes for the title, e.g. `text-destructive` for danger sections. */
+    titleClassName?: string;
+}
+/**
+ * Standard section heading used across settings screens:
+ * `h3 text-sm font-medium` title + muted `text-sm` description.
+ * Renders nothing when both title and description are empty.
+ */
+declare function SectionHeader({ title, description, actions, className, titleClassName, }: SectionHeaderProps): react_jsx_runtime.JSX.Element | null;
+
+interface SidebarNavSectionProps {
+    /** Uppercase group label shown above the items. */
+    title: string;
+    children: React$1.ReactNode;
+    className?: string;
+}
+/** Labeled group of sidebar items. */
+declare function SidebarNavSection({ title, children, className }: SidebarNavSectionProps): react_jsx_runtime.JSX.Element;
+interface SidebarNavItemProps {
+    /** Leading icon, e.g. `<UserIcon className="h-3.5 w-3.5" />` */
+    icon?: React$1.ReactNode;
+    label: string;
+    /** Highlights the item as the current selection. */
+    active?: boolean;
+    onClick?: () => void;
+    className?: string;
+}
+/**
+ * Single sidebar navigation entry with the standard active/hover styling.
+ * Mobile-friendly by default: comfortable ~44px touch target and a trailing
+ * chevron affordance below the `sm` breakpoint; compact rows on desktop.
+ */
+declare function SidebarNavItem({ icon, label, active, onClick, className }: SidebarNavItemProps): react_jsx_runtime.JSX.Element;
+
+type StatusBannerVariant = 'error' | 'success' | 'warning' | 'info';
+interface StatusBannerProps {
+    variant: StatusBannerVariant;
+    /** Bold first line, e.g. "Error loading subscription data". */
+    title?: string;
+    /** Body text under the title (or standalone when there is no title). */
+    message?: string;
+    /** Small hint line under the message, e.g. "Retrying may resolve this." */
+    description?: string;
+    /** Optional leading icon, e.g. `<CheckCircle2 className="h-4 w-4 shrink-0" />`. */
+    icon?: React$1.ReactNode;
+    /** Label for the action button (Retry, Dismiss, …). Button renders only when set. */
+    actionLabel?: string;
+    onAction?: () => void;
+    actionDisabled?: boolean;
+    className?: string;
+}
+/**
+ * Standard status banner for error / success / warning / info feedback,
+ * with an optional Retry/Dismiss action. Use for every inline status box
+ * so all screens share the same look.
+ */
+declare function StatusBanner({ variant, title, message, description, icon, actionLabel, onAction, actionDisabled, className, }: StatusBannerProps): react_jsx_runtime.JSX.Element;
+
 declare function WorkspaceSwitcher(props: {
     trigger: (isLoading: boolean, currentWorkspace: IWorkspace | null) => ReactNode;
 }): react_jsx_runtime.JSX.Element;
@@ -5414,19 +5780,43 @@ interface PushNotificationContextValue extends PushNotificationState {
     unsubscribe: () => Promise<void>;
 }
 interface PushNotificationProviderProps {
-    children: react__default.ReactNode;
+    children: React__default.ReactNode;
     /** Path to the service worker file (default: '/push-sw.js') */
     serviceWorkerPath?: string;
     /** Automatically subscribe after permission is granted on login (default: false) */
     autoSubscribe?: boolean;
 }
-declare const PushNotificationProvider: react__default.FC<PushNotificationProviderProps>;
+declare const PushNotificationProvider: React__default.FC<PushNotificationProviderProps>;
 /**
  * Hook to access push notification state and actions.
  * Must be used within PushNotificationProvider (included in SaaSOSProvider when push config is provided).
  */
 declare function usePushNotifications(): PushNotificationContextValue;
 
+/**
+ * Single-call visibility decisions combining the implementor's `ui` config
+ * with platform permissions.
+ *
+ * A piece of UI is visible when its config flag is not explicitly `false`
+ * AND the optional permission check passes. Config can only hide UI —
+ * permissions remain the security floor.
+ *
+ * @example
+ * ```tsx
+ * const { visible } = useUIVisibility();
+ *
+ * // Config flag only
+ * visible(ui => ui.settings?.credits?.buyButton)
+ *
+ * // Config flag AND permission — one line decides show/hide
+ * visible(ui => ui.settings?.sections?.users, Permission.WORKSPACE_MEMBERS_VIEW)
+ * ```
+ */
+declare function useUIVisibility(): {
+    visible: (select: (ui: SDKUIConfig) => boolean | undefined, permission?: string | string[]) => boolean;
+    ui: SDKUIConfig;
+};
+
 interface SettingsManagerState {
     open: boolean;
     section: WorkspaceSettingsSection;
@@ -5470,5 +5860,5 @@ declare class WorkspaceSettingsManager {
 }
 declare const workspaceSettingsManager: WorkspaceSettingsManager;
 
-export { ApiVersion, AuthApi, AuthStatus, BBAction, BBScreen, BBStatus, BB_PARAM, BaseApi, BetaForm, BillingIntervals, CURRENCY_DISPLAY, CURRENCY_FLAG, CreditActionsProvider, CreditBalance, CreditBalanceContextProvider, CreditBucketSource, CreditBucketStatus, CreditStorePage, CreditTransactionType, DEFAULT_ROLE_PERMISSIONS, DunningState, EventEmitter, FullScreenLoader, InvoiceStatuses, PLAN_CURRENCY_CODES, PLAN_CURRENCY_OPTIONS, PUSH_SERVICE_WORKER_SCRIPT, Permission, PricingPage, PushApi, PushNotificationProvider, QuotaUsageContextProvider, SDKEvent, SETTINGS_SCREENS, SUPPORTED_LOCALES, SaaSOSProvider, SettingsApi, SettingsScreen, 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, readBBParams, resolveMaxUsers, resolvePermissions, safeRedirect, saveAuthIntent, useAllQuotaUsage, useBillingPortal, useCancelSubscription, 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, useUpdateSubscription, useUsageLogs, useUserAttributes, useUserFeatures, validateInvite, validateRedirectUrl, workspaceSettingsManager };
-export type { BBActionType, BBScreenType, BBStatusType, BetaFormData, BetaFormResponse, BillingInterval, CheckoutResult, CreditActionsDetails, CreditBalanceContextValue, CreditBalanceDetails, CreditBucketSourceType, CreditBucketStatusType, CreditStorePageDetails, CreditTransactionTypeValue, DunningStateType, EventData, EventType, FormatQuotaWithPriceOptions, FullScreenLoaderProps, GetCheckoutStripeParams, IAllQuotaUsageResponse, IBaseApiConfig, IBasePricing, IBetaConfig, ICheckoutSessionRequest, ICheckoutSessionResponse, ICheckoutStripeOptions, 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, IStripePricesByInterval, ISubscription, ISubscriptionItem, ISubscriptionResponse, ISubscriptionUpdateRequest, ISubscriptionUpdateResponse, IUsageLogEntry, IUsageLogsQuery, IUsageLogsResponse, InviteBlockReason, InviteValidation, InvoiceStatus, InvoiceStatusType, LoadingProps, MaxUsersConfig, NotificationData, NotificationEvent, NotificationResult, OnWorkspaceChangeParams, PermissionContext, PermissionKey, PlanVersionWithPricingVariants, PricingPageDetails, PricingPageProps, QuotaDisplayValue, QuotaDisplayWithOverage, QuotaUsageContextValue, RolePermissionMap, SDKLocale, SDKMessages, SaaSOSProviderProps, SeatStatus, SettingsManagerState, SubscriptionContextValue, SubscriptionItemTypeValue, SubscriptionStatusType, TrialStatus, UserCreatedEventData, UserUpdatedEventData, WorkspaceChangedEventData, WorkspaceCreatedEventData, WorkspaceDeletedEventData, WorkspaceSettingsSection, WorkspaceUpdatedEventData, WorkspaceUserAddedEventData, WorkspaceUserRemovedEventData, WorkspaceUserRoleChangedEventData };
+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, mergeUIConfig, 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, IStripePricesByInterval, ISubscription, ISubscriptionItem, ISubscriptionResponse, ISubscriptionUpdateRequest, ISubscriptionUpdateResponse, IUsageLogEntry, IUsageLogsQuery, IUsageLogsResponse, InviteBlockReason, InviteValidation, InvoiceStatus, InvoiceStatusType, LoadingProps, LoadingStateProps, MaxUsersConfig, NotificationData, NotificationEvent, NotificationResult, OnWorkspaceChangeParams, PartialSDKMessages, PermissionContext, PermissionKey, PlanVersionWithPricingVariants, PricingPageDetails, PricingPageProps, QuotaDisplayValue, QuotaDisplayWithOverage, QuotaUsageContextValue, RolePermissionMap, SDKLocale, SDKMessages, SDKUIConfig, SaaSOSProviderProps, SeatStatus, SectionHeaderProps, SettingsManagerState, SidebarNavItemProps, SidebarNavSectionProps, StatusBannerProps, StatusBannerVariant, SubscriptionContextValue, SubscriptionItemTypeValue, SubscriptionStatusType, TrialStatus, UseConnectedAgents, UserCreatedEventData, UserUpdatedEventData, WorkspaceChangedEventData, WorkspaceCreatedEventData, WorkspaceDeletedEventData, WorkspaceSettingsSection, WorkspaceUpdatedEventData, WorkspaceUserAddedEventData, WorkspaceUserRemovedEventData, WorkspaceUserRoleChangedEventData };