@buildbase/sdk 0.0.15 → 0.0.18

package/dist/index.d.ts

@@ -21,10 +21,14 @@ interface IUser extends IDocument {
     currency: string;
     attributes?: Record<string, string | number | boolean>;
 }
+type BillingInterval = 'monthly' | 'yearly' | 'quarterly';
 interface ISubscription {
     _id: string;
     subscriptionStatus: 'active' | 'trialing' | 'canceled' | 'past_due';
+    stripePriceId?: string;
+    stripeCurrentPeriodEnd?: string;
     cancelAtPeriodEnd: boolean;
+    billingInterval?: BillingInterval;
     createdAt: string;
     updatedAt: string;
     plan?: {
@@ -47,6 +51,20 @@ interface IQuotaValue {
     overage?: number;
     stripePriceId?: string;
 }
+/** Per-interval quota value (new plan-group/versions schema) */
+interface IQuotaIntervalValue {
+    included: number;
+    overage: number;
+    priceId: string;
+    /** Optional unit size for overage pricing (e.g. 1000 = price per 1000 units). */
+    unitSize?: number;
+}
+/** Quota defined per billing interval (new plan-group/versions schema) */
+interface IQuotaByInterval {
+    monthly?: IQuotaIntervalValue;
+    yearly?: IQuotaIntervalValue;
+    quarterly?: IQuotaIntervalValue;
+}
 interface IBasePricing {
     monthly: number;
     yearly: number;
@@ -59,7 +77,8 @@ interface IPlanVersion {
     status: 'draft' | 'published';
     features?: Record<string, boolean>;
     limits?: Record<string, number>;
-    quotas?: Record<string, number | IQuotaValue>;
+    /** Legacy: number | IQuotaValue. New schema: IQuotaByInterval (per-interval included/overage/priceId) */
+    quotas?: Record<string, number | IQuotaValue | IQuotaByInterval>;
     basePricing?: IBasePricing;
     stripePrices?: {
         monthlyPriceId?: string;
@@ -76,13 +95,18 @@ interface IPlanVersion {
     createdAt?: string;
     updatedAt?: string;
     id?: string;
+    stripeProductId?: string;
+}
+/** Plan version summary (e.g. plan.latestVersion from subscription API) with subscriptionItems as IDs. */
+interface IPlanVersionSummary extends Omit<IPlanVersion, 'subscriptionItems'> {
+    subscriptionItems?: string[];
 }
 interface IPlan {
     _id: string;
     name: string;
     slug: string;
     description?: string;
-    latestVersion?: IPlanVersion;
+    latestVersion?: IPlanVersionSummary;
     archived?: boolean;
     deleted?: boolean;
     createdAt?: string;
@@ -157,25 +181,26 @@ interface IPlanGroupVersionWithPlans {
         removedPlans: IPlanVersionWithPlan[];
     };
 }
+interface IPlanGroupInfo {
+    _id: string;
+    name: string;
+    slug: string;
+    description?: string;
+}
+/** Response from GET workspaces/:id/subscription/plan-group (and by version). */
 interface IPlanGroupResponse {
-    group: {
-        _id: string;
-        name: string;
-        slug: string;
-    };
-    currentVersion: IPlanGroupVersionWithPlans;
-    availableVersions: IPlanGroupVersionWithPlans[];
+    /** Plan group with latestVersion, archived, deleted, timestamps. */
+    group: IPlanGroup;
+    /** Current group version with populated planVersionIds (or IDs). */
+    groupVersion: IPlanGroupVersion;
+    /** Full plan versions for display (subscriptionItems, basePricing, quotas, etc.). */
+    plans: IPlanVersionWithPlan[];
 }
 interface IPlanGroupVersionsResponse {
-    group: {
-        _id: string;
-        name: string;
-        slug: string;
-    };
+    group: IPlanGroupInfo;
     currentVersion: IPlanGroupVersionWithPlans;
     availableVersions: IPlanGroupVersionWithPlans[];
 }
-type BillingInterval = 'monthly' | 'yearly' | 'quarterly';
 interface ICheckoutSessionRequest {
     planVersionId: string;
     billingInterval?: BillingInterval;
@@ -510,7 +535,7 @@ interface PricingPageProps {
  * </PricingPage>
  * ```
  */
-declare function PricingPage({ slug, children, loadingFallback, errorFallback, }: PricingPageProps): react_jsx_runtime.JSX.Element;
+declare function PricingPage({ slug, children, loadingFallback, errorFallback }: PricingPageProps): react_jsx_runtime.JSX.Element;
 
 interface IProps$2 {
     children: React.ReactNode;
@@ -778,69 +803,149 @@ declare const WhenUserFeatureEnabled: (props: IProps) => react.ReactNode;
  */
 declare const WhenUserFeatureDisabled: (props: IProps) => react.ReactNode;
 
-type WorkspaceSettingsSection = 'profile' | 'general' | 'users' | 'subscription' | 'features' | 'danger';
-
+interface IWhenSubscriptionProps {
+    /** Content to render when the condition is met (workspace has an active subscription). */
+    children: React.ReactNode;
+    /** Optional component/element to show while subscription is loading (e.g. <Skeleton />). */
+    loadingComponent?: React.ReactNode;
+    /** Optional component/element to show when condition is not met (e.g. <UpgradePrompt />). */
+    fallbackComponent?: React.ReactNode;
+}
 /**
- * Main authentication hook for the SDK.
- * Provides authentication state, user session, and auth actions.
+ * Renders children only when the current workspace has an active subscription (any plan).
+ * Optionally pass loadingComponent (while loading) or fallbackComponent (when not subscribed).
+ * Must be used within SubscriptionContextProvider.
  *
- * @returns An object containing:
- * - `user`: Current authenticated user object (null if not authenticated)
- * - `session`: Full session object with user and token (null if not authenticated)
- * - `status`: Current authentication status (loading, redirecting, authenticating, authenticated, unauthenticated)
- * - `isLoading`: Boolean indicating if auth state is being determined
- * - `isAuthenticated`: Boolean indicating if user is authenticated
- * - `isRedirecting`: Boolean indicating if redirecting to OAuth provider
- * - `signIn()`: Function to initiate OAuth sign-in flow
- * - `signOut()`: Function to sign out the current user
- * - `openWorkspaceSettings(section?)`: Function to open workspace settings dialog
+ * @param props - Component props
+ * @param props.children - Content to render when subscribed
+ * @param props.loadingComponent - Optional component/element to show while loading
+ * @param props.fallbackComponent - Optional component/element to show when not subscribed
+ * @returns ReactNode - children when subscribed, loadingComponent when loading, fallbackComponent when not subscribed, or null
  *
  * @example
  * ```tsx
- * function MyComponent() {
- *   const { user, isAuthenticated, signIn, signOut } = useSaaSAuth();
+ * <WhenSubscription>
+ *   <BillingSettings />
+ * </WhenSubscription>
+ * ```
  *
- *   if (!isAuthenticated) {
- *     return <button onClick={signIn}>Sign In</button>;
- *   }
+ * @example
+ * ```tsx
+ * <WhenSubscription
+ *   loadingComponent={<Skeleton />}
+ *   fallbackComponent={<UpgradePrompt />}
+ * >
+ *   <BillingSettings />
+ * </WhenSubscription>
+ * ```
+ */
+declare const WhenSubscription: (props: IWhenSubscriptionProps) => react.ReactNode;
+/**
+ * Renders children only when the current workspace has no subscription (or no current workspace).
+ * Optionally pass loadingComponent (while loading) or fallbackComponent (when already subscribed).
+ * Must be used within SubscriptionContextProvider.
  *
- *   return (
- *     <div>
- *       <p>Welcome, {user?.name}</p>
- *       <button onClick={signOut}>Sign Out</button>
- *     </div>
- *   );
- * }
+ * @param props - Component props
+ * @param props.children - Content to render when not subscribed
+ * @param props.loadingComponent - Optional component/element to show while loading
+ * @param props.fallbackComponent - Optional component/element to show when already subscribed
+ * @returns ReactNode - children when not subscribed, loadingComponent when loading, fallbackComponent when subscribed, or null
+ *
+ * @example
+ * ```tsx
+ * <WhenNoSubscription>
+ *   <UpgradePrompt />
+ * </WhenNoSubscription>
  * ```
  *
  * @example
  * ```tsx
- * // Handle loading state
- * function App() {
- *   const { status, isLoading } = useSaaSAuth();
+ * <WhenNoSubscription
+ *   loadingComponent={<Spinner />}
+ *   fallbackComponent={null}
+ * >
+ *   <UpgradePrompt />
+ * </WhenNoSubscription>
+ * ```
+ */
+declare const WhenNoSubscription: (props: IWhenSubscriptionProps) => react.ReactNode;
+interface IWhenSubscriptionToPlansProps {
+    /** Plan slugs to match (e.g. ['pro', 'enterprise']). Matching is case-insensitive. */
+    plans: string[];
+    /** Content to render when the workspace is on one of the given plans. */
+    children: React.ReactNode;
+    /** Optional component/element to show while subscription is loading (e.g. <Skeleton />). */
+    loadingComponent?: React.ReactNode;
+    /** Optional component/element to show when not on a matching plan (e.g. <UpgradeToPro />). */
+    fallbackComponent?: React.ReactNode;
+}
+/**
+ * Renders children only when the current workspace is subscribed to one of the given plans.
+ * Matches by plan slug only. Optionally pass loadingComponent (while loading) or fallbackComponent (when not on a matching plan).
+ * Must be used within SubscriptionContextProvider.
  *
- *   if (isLoading) {
- *     return <LoadingSpinner />;
- *   }
+ * @param props - Component props
+ * @param props.plans - Plan slugs to match (e.g. ['pro', 'enterprise'])
+ * @param props.children - Content to render when on a matching plan
+ * @param props.loadingComponent - Optional component/element to show while loading
+ * @param props.fallbackComponent - Optional component/element to show when not on a matching plan
+ * @returns ReactNode - children when on a matching plan, loadingComponent when loading, fallbackComponent when not matching, or null
  *
- *   return <MainContent />;
- * }
+ * @example
+ * ```tsx
+ * <WhenSubscriptionToPlans plans={['pro', 'enterprise']}>
+ *   <AdvancedAnalytics />
+ * </WhenSubscriptionToPlans>
  * ```
  *
  * @example
  * ```tsx
- * // Open workspace settings
- * function SettingsButton() {
- *   const { openWorkspaceSettings } = useSaaSAuth();
- *
- *   return (
- *     <button onClick={() => openWorkspaceSettings('general')}>
- *       Open Settings
- *     </button>
- *   );
- * }
+ * <WhenSubscriptionToPlans
+ *   plans={['pro', 'enterprise']}
+ *   loadingComponent={<Skeleton />}
+ *   fallbackComponent={<UpgradeToPro />}
+ * >
+ *   <AdvancedAnalytics />
+ * </WhenSubscriptionToPlans>
  * ```
  */
+declare const WhenSubscriptionToPlans: (props: IWhenSubscriptionToPlansProps) => react.ReactNode;
+
+/**
+ * Value provided by SubscriptionContext and returned by useSubscriptionContext.
+ */
+interface SubscriptionContextValue {
+    /** Current subscription response for the current workspace, or null if none or not loaded. */
+    response: ISubscriptionResponse | null;
+    /** True while subscription is being fetched. */
+    loading: boolean;
+    /** Refetch subscription for the current workspace. Call after plan change (e.g. upgrade) or when subscription was updated elsewhere. */
+    refetch: () => Promise<void>;
+}
+
+/**
+ * Provides subscription data for the current workspace to subscription gate components.
+ * Fetches when workspace changes; refetches when subscription is invalidated (e.g. after plan change).
+ * Must wrap (or be ancestor of) any component that uses WhenSubscription, WhenNoSubscription,
+ * WhenSubscriptionToPlans, or useSubscriptionContext. Included in SaaSOSProvider by default.
+ *
+ * @param props - Component props
+ * @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<{
+    children: ReactNode;
+}>;
+/**
+ * Returns subscription data for the current workspace. Must be used within SubscriptionContextProvider.
+ *
+ * @returns SubscriptionContextValue - { response, loading, refetch }
+ * @throws Error if used outside SubscriptionContextProvider
+ */
+declare function useSubscriptionContext(): SubscriptionContextValue;
+
+type WorkspaceSettingsSection = 'profile' | 'general' | 'users' | 'subscription' | 'features' | 'danger';
+
 declare function useSaaSAuth(): {
     signIn: () => Promise<void>;
     signOut: () => Promise<void>;
@@ -853,6 +958,11 @@ declare function useSaaSAuth(): {
     status: AuthStatus;
 };
 
+/**
+ * Hook to access OS (organization) state (serverUrl, version, orgId, auth, settings).
+ * Prefer useSaaSSettings() when you only need settings.
+ */
+declare function useSaaSOs(): IOsState;
 /**
  * Hook to access organization settings from the OS context.
  * Automatically fetches settings when OS config is ready.
@@ -908,6 +1018,68 @@ interface UserContextValue {
     refreshFeatures: () => Promise<void>;
 }
 
+/**
+ * Base API client for SDK endpoints.
+ * All domain API classes (WorkspaceApi, UserApi, etc.) extend this to share
+ * URL building, auth headers, and request/response handling.
+ */
+
+interface IBaseApiConfig {
+    serverUrl: string;
+    version: ApiVersion;
+    orgId?: string;
+    /** When true, ensureReady() also requires orgId. Used by WorkspaceApi and SettingsApi. */
+    requireOrgId?: boolean;
+    /** API path segment after version (default 'public'). e.g. 'public' => .../v1/public, 'beta' => .../v1/beta */
+    basePath?: string;
+}
+/**
+ * Base class for SDK API clients.
+ * Provides:
+ * - baseUrl: `${serverUrl}/api/${version}/public`
+ * - getAuthHeaders()
+ * - fetchJson<T>(path, init, errorMessage): GET/POST/etc. with handleApiResponse
+ * - fetchResponse(path, init): raw Response for custom parsing (e.g. non-JSON or custom error handling)
+ */
+declare abstract class BaseApi {
+    protected readonly serverUrl: string;
+    protected readonly version: ApiVersion;
+    protected readonly orgId: string | undefined;
+    private readonly requireOrgId;
+    private readonly basePath;
+    constructor(config: IBaseApiConfig);
+    /** Throws if config is not ready for API calls. Called automatically by fetchJson/fetchResponse. */
+    protected ensureReady(): void;
+    /** Base URL: ${serverUrl}/api/${version}/${basePath} */
+    protected get baseUrl(): string;
+    /** Auth headers (x-session-id). Subclasses can override to add more. */
+    protected getAuthHeaders(): Record<string, string>;
+    /** Build full URL from path (path can be "workspaces" or "/workspaces"). */
+    protected url(path: string): string;
+    /**
+     * Execute request and parse JSON with handleApiResponse (throws on !response.ok).
+     * Use for standard JSON APIs.
+     */
+    protected fetchJson<T>(path: string, init?: RequestInit, errorMessage?: string): Promise<T>;
+    /**
+     * Execute request and return raw Response (for custom parsing or error handling).
+     * Caller is responsible for checking response.ok and parsing body.
+     */
+    protected fetchResponse(path: string, init?: RequestInit): Promise<Response>;
+}
+
+/**
+ * Centralized API client for user attributes and features.
+ * Extends BaseApi for shared URL/auth/request handling.
+ */
+declare class UserApi extends BaseApi {
+    constructor(config: Pick<IOsConfig, 'serverUrl' | 'version'>);
+    getAttributes(signal?: AbortSignal): Promise<Record<string, string | number | boolean>>;
+    updateAttributes(updates: Record<string, string | number | boolean>): Promise<IUser>;
+    updateAttribute(attributeKey: string, value: string | number | boolean): Promise<IUser>;
+    getFeatures(signal?: AbortSignal): Promise<Record<string, boolean>>;
+}
+
 /**
  * Hook to access user attributes from the UserProvider.
  * Must be used within a UserProvider component.
@@ -988,111 +1160,131 @@ declare function useUserFeatures(): {
     isFeatureEnabled: (featureId: string) => boolean;
 };
 
-/**
- * Main workspace management hook for the SDK.
- * Provides workspace state, CRUD operations, and user management.
- *
- * @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 class WorkspaceApi extends BaseApi {
+    constructor(config: IOsConfig);
+    getWorkspaces(): Promise<IWorkspace[]>;
+    createWorkspace(data: {
+        name: string;
+        image?: string;
+    }): Promise<IWorkspace>;
+    updateWorkspace(id: string, data: Partial<IWorkspace>): Promise<IWorkspace>;
+    deleteWorkspace(id: string): Promise<{
+        success: boolean;
+    }>;
+    getWorkspaceUsers(workspaceId: string): Promise<IWorkspaceUser[]>;
+    addUser(workspaceId: string, config: {
+        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, data: Partial<IWorkspaceUser>): Promise<{
+        userId: string;
+        workspace: IWorkspace;
+        message: string;
+    }>;
+    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>;
+    /**
+     * Get current subscription for a workspace
+     * Returns subscription details including plan, plan version, and group information
+     */
+    getCurrentSubscription(workspaceId: string): 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>;
+    /**
+     * 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>;
+    /**
+     * Get current group version and available newer versions of the same group
+     * - If user has active subscription: returns their current group version + newer versions
+     * - If no subscription: returns the latest published group version
+     * Shows what's new in newer versions to help users upgrade
+     * Example: User on Group v1 (Basic Plan) can see Group v2 (Basic + Pro Plan)
+     * @param workspaceId - The workspace ID
+     * @returns Plan group versions response with currentVersion and availableVersions
+     */
+    getPlanGroupVersions(workspaceId: string): 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.
+     * Use this for public pricing pages when you want to show a specific plan group.
+     *
+     * @param slug - Plan group slug (e.g. 'default', 'enterprise')
+     * @returns Plan group versions response with currentVersion and availableVersions
+     */
+    getPublicPlans(slug: string): Promise<IPublicPlansResponse>;
+    /**
+     * Get plan group version details by ID (public, no auth required).
+     * Returns the full plan group version with populated plan versions.
+     * Use this for public pricing pages when you have the groupVersionId (e.g. from config or URL).
+     *
+     * @param groupVersionId - The plan group version ID to fetch
+     * @returns Plan group version with populated plan versions
+     */
+    getPlanGroupVersion(groupVersionId: string): 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<ICheckoutSessionResponse>;
+    /**
+     * Update subscription (upgrade/downgrade)
+     * 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>;
+    /**
+     * List invoices for a workspace subscription
+     * @param workspaceId - The workspace ID
+     * @param limit - Number of invoices to return (default: 10)
+     * @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>;
+    /**
+     * 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>;
+    /**
+     * 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>;
+    /**
+     * 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>;
+}
+
 declare const useSaaSWorkspaces: () => {
     workspaces: IWorkspace[];
     loading: boolean;
@@ -1136,6 +1328,7 @@ declare const useSaaSWorkspaces: () => {
         success: boolean;
     }>;
     switching: boolean;
+    switchingToId: string | null;
 };
 
 declare function WorkspaceSwitcher(props: {
@@ -1263,7 +1456,7 @@ declare const useSubscription: (workspaceId: string | null | undefined) => {
  *
  *   return (
  *     <div>
- *       <h3>{planGroup.name}</h3>
+ *       <h3>{planGroup.group.name}</h3>
  *       {planGroup.plans.map(plan => (
  *         <PlanCard key={plan._id} plan={plan} />
  *       ))}
@@ -1703,5 +1896,39 @@ declare class EventEmitter {
 }
 declare const eventEmitter: EventEmitter;
 
-export { ApiVersion, AuthStatus, BetaForm, PricingPage, SaaSOSProvider, WhenAuthenticated, WhenRoles, WhenUnauthenticated, WhenUserFeatureDisabled, WhenUserFeatureEnabled, WhenWorkspaceFeatureDisabled, WhenWorkspaceFeatureEnabled, WhenWorkspaceRoles, WorkspaceSwitcher, eventEmitter, useCreateCheckoutSession, useInvoice, useInvoices, usePlanGroup, usePlanGroupVersions, usePublicPlanGroupVersion, usePublicPlans, useSaaSAuth, useSaaSSettings, useSaaSWorkspaces, useSubscription, useSubscriptionManagement, useUpdateSubscription, useUserAttributes, useUserFeatures };
-export type { BillingInterval, EventData, EventType, IBasePricing, ICheckoutSessionRequest, ICheckoutSessionResponse, IEventCallbacks, IInvoice, IInvoiceListResponse, IInvoiceResponse, IPlan, IPlanGroup, IPlanGroupLatestVersion, IPlanGroupResponse, IPlanGroupVersion, IPlanGroupVersionWithPlans, IPlanGroupVersionsResponse, IPlanVersion, IPlanVersionWithPlan, IPublicPlanItem, IPublicPlanItemCategory, IPublicPlanPricing, IPublicPlanQuotaValue, IPublicPlanVersion, IPublicPlansResponse, IQuotaValue, ISubscription, ISubscriptionItem, ISubscriptionResponse, ISubscriptionUpdateRequest, ISubscriptionUpdateResponse, InvoiceStatus, OnWorkspaceChangeParams, PricingPageDetails, PricingPageProps, UserCreatedEventData, UserUpdatedEventData, WorkspaceChangedEventData, WorkspaceCreatedEventData, WorkspaceDeletedEventData, WorkspaceUpdatedEventData, WorkspaceUserAddedEventData, WorkspaceUserRemovedEventData, WorkspaceUserRoleChangedEventData };
+/**
+ * Centralized API client for organization (OS) settings.
+ * Extends BaseApi for shared URL/auth/request handling.
+ */
+
+declare class SettingsApi extends BaseApi {
+    constructor(config: IOsConfig);
+    getSettings(signal?: AbortSignal): Promise<ISettings>;
+}
+
+type QuotaDisplayValue = {
+    included: number;
+    overage?: number;
+    unitSize?: number;
+} | number | null;
+/**
+ * Normalize a quota value (legacy or per-interval) to a display shape for a given billing interval.
+ * - Legacy: number or IQuotaValue → use as-is (interval ignored).
+ * - New schema: IQuotaByInterval → pick the interval slice (e.g. monthly, yearly, quarterly).
+ */
+declare function getQuotaDisplayValue(value: number | IQuotaValue | IQuotaByInterval | null | undefined, interval?: BillingInterval): QuotaDisplayValue;
+/** Options for formatting quota with price. */
+interface FormatQuotaWithPriceOptions {
+    /** If true, overage is in cents (Stripe); format as dollars. Default true. */
+    overageInCents?: boolean;
+    /** Currency symbol. Default '$'. */
+    currencySymbol?: string;
+}
+/**
+ * Format a quota display value as "X included, then $Y.YY / unit" (e.g. "10 included, then $10.00 / video").
+ * Assumes overage is the per-unit price (in cents when overageInCents is true).
+ */
+declare function formatQuotaWithPrice(value: QuotaDisplayValue, unitName: string, options?: FormatQuotaWithPriceOptions): string;
+
+export { ApiVersion, AuthStatus, BaseApi, BetaForm, PricingPage, SaaSOSProvider, SettingsApi, SubscriptionContextProvider, UserApi, WhenAuthenticated, WhenNoSubscription, WhenRoles, WhenSubscription, WhenSubscriptionToPlans, WhenUnauthenticated, WhenUserFeatureDisabled, WhenUserFeatureEnabled, WhenWorkspaceFeatureDisabled, WhenWorkspaceFeatureEnabled, WhenWorkspaceRoles, WorkspaceApi, WorkspaceSwitcher, eventEmitter, formatQuotaWithPrice, getQuotaDisplayValue, useCreateCheckoutSession, useInvoice, useInvoices, usePlanGroup, usePlanGroupVersions, usePublicPlanGroupVersion, usePublicPlans, useSaaSAuth, useSaaSOs, useSaaSSettings, useSaaSWorkspaces, useSubscription, useSubscriptionContext, useSubscriptionManagement, useUpdateSubscription, useUserAttributes, useUserFeatures };
+export type { BillingInterval, EventData, EventType, FormatQuotaWithPriceOptions, IBaseApiConfig, IBasePricing, ICheckoutSessionRequest, ICheckoutSessionResponse, IEventCallbacks, IInvoice, IInvoiceListResponse, IInvoiceResponse, IPlan, IPlanGroup, IPlanGroupInfo, IPlanGroupLatestVersion, IPlanGroupResponse, IPlanGroupVersion, IPlanGroupVersionWithPlans, IPlanGroupVersionsResponse, IPlanVersion, IPlanVersionSummary, IPlanVersionWithPlan, IPublicPlanItem, IPublicPlanItemCategory, IPublicPlanPricing, IPublicPlanQuotaValue, IPublicPlanVersion, IPublicPlansResponse, IQuotaByInterval, IQuotaIntervalValue, IQuotaValue, ISubscription, ISubscriptionItem, ISubscriptionResponse, ISubscriptionUpdateRequest, ISubscriptionUpdateResponse, InvoiceStatus, OnWorkspaceChangeParams, PricingPageDetails, PricingPageProps, QuotaDisplayValue, SubscriptionContextValue, UserCreatedEventData, UserUpdatedEventData, WorkspaceChangedEventData, WorkspaceCreatedEventData, WorkspaceDeletedEventData, WorkspaceUpdatedEventData, WorkspaceUserAddedEventData, WorkspaceUserRemovedEventData, WorkspaceUserRoleChangedEventData };