@buildbase/sdk 0.0.16 → 0.0.19

package/dist/index.d.ts

@@ -4,7 +4,8 @@ import * as react_jsx_runtime from 'react/jsx-runtime';
 
 interface IDocument {
     _id: string;
-    id: string;
+    /** Optional; some APIs only return _id. Prefer _id for identity. */
+    id?: string;
     createdAt: string;
     updatedAt: string;
     deleted: boolean;
@@ -13,12 +14,17 @@ interface IUser extends IDocument {
     _id: string;
     name: string;
     email: string;
-    image: string;
+    /** Profile image URL. Often omitted or empty from API. */
+    image?: string;
     role: string;
-    country: string;
-    timezone: string;
-    language: string;
-    currency: string;
+    /** ISO country code. May be omitted. */
+    country?: string;
+    /** IANA timezone. May be omitted. */
+    timezone?: string;
+    /** Language code. May be omitted. */
+    language?: string;
+    /** Currency code. May be omitted. */
+    currency?: string;
     attributes?: Record<string, string | number | boolean>;
 }
 type BillingInterval = 'monthly' | 'yearly' | 'quarterly';
@@ -28,6 +34,7 @@ interface ISubscription {
     stripePriceId?: string;
     stripeCurrentPeriodEnd?: string;
     cancelAtPeriodEnd: boolean;
+    billingInterval?: BillingInterval;
     createdAt: string;
     updatedAt: string;
     plan?: {
@@ -35,6 +42,8 @@ interface ISubscription {
         name: string;
         slug: string;
         description?: string;
+        /** Stripe currency code (e.g. 'usd', 'inr', 'eur'). */
+        currency?: string;
     };
 }
 interface ISubscriptionItem {
@@ -45,16 +54,62 @@ interface ISubscriptionItem {
     description?: string;
     category: string;
 }
-interface IQuotaValue {
+/** Per-interval quota value (plan-group/versions and public plans schema). */
+interface IQuotaIntervalValue {
     included: number;
+    /** Overage price in cents. Omitted in public plans; use pricingVariant.quotaOverages for display. */
     overage?: number;
-    stripePriceId?: string;
+    /** Stripe price ID for overage. Omitted in public plans; use pricingVariant.quotaOveragePriceIds. */
+    priceId?: string;
+    /** 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;
 }
+/** Base pricing per interval. Values are often in cents (Stripe); convert for display. */
 interface IBasePricing {
     monthly: number;
     yearly: number;
     quarterly: number;
 }
+/** Stripe price IDs per billing interval (for a single currency variant). */
+interface IStripePricesByInterval {
+    monthlyPriceId?: string;
+    yearlyPriceId?: string;
+    quarterlyPriceId?: string;
+    monthly?: string;
+    yearly?: string;
+}
+/** Overage amounts in cents per interval, keyed by quota slug. Used in pricing variants. */
+type IQuotaOveragesByInterval = Record<string, {
+    monthly?: number;
+    yearly?: number;
+    quarterly?: number;
+}>;
+/** Overage Stripe price IDs per interval, keyed by quota slug. Used in pricing variants. */
+type IQuotaOveragePriceIdsByInterval = Record<string, {
+    monthly?: string;
+    yearly?: string;
+    quarterly?: string;
+}>;
+/**
+ * Multi-currency pricing variant at plan version level.
+ * Each plan version can have multiple variants (e.g. usd, eur, inr, sgd).
+ */
+interface IPricingVariant {
+    _id: string;
+    currency: string;
+    basePricing: IBasePricing;
+    stripePrices: IStripePricesByInterval;
+    /** Overage cents per quota slug per interval. */
+    quotaOverages?: IQuotaOveragesByInterval;
+    /** Stripe price IDs for overage per quota slug per interval. */
+    quotaOveragePriceIds?: IQuotaOveragePriceIdsByInterval;
+}
 interface IPlanVersion {
     _id: string;
     version: number;
@@ -62,15 +117,10 @@ interface IPlanVersion {
     status: 'draft' | 'published';
     features?: Record<string, boolean>;
     limits?: Record<string, number>;
-    quotas?: Record<string, number | IQuotaValue>;
-    basePricing?: IBasePricing;
-    stripePrices?: {
-        monthlyPriceId?: string;
-        yearlyPriceId?: string;
-        quarterlyPriceId?: string;
-        monthly?: string;
-        yearly?: string;
-    };
+    /** Per-interval quotas (included, unitSize; overage from pricingVariant.quotaOverages). */
+    quotas?: Record<string, IQuotaByInterval>;
+    /** Multi-currency pricing. Each variant has currency, basePricing, stripePrices, quotaOverages. */
+    pricingVariants?: IPricingVariant[];
     subscriptionItems?: ISubscriptionItem[];
     isCurrent?: boolean;
     isLegacy?: boolean;
@@ -79,13 +129,20 @@ 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;
+    /** Stripe currency code (e.g. 'usd', 'inr', 'eur'). Used for pricing display. */
+    currency?: string;
+    latestVersion?: IPlanVersionSummary;
     archived?: boolean;
     deleted?: boolean;
     createdAt?: string;
@@ -145,13 +202,19 @@ interface ISubscriptionResponse {
     group: IPlanGroup | null;
     groupVersion: IPlanGroupVersion | null;
 }
+/** Plan version with nested plan info (name, slug, currency for display). */
 interface IPlanVersionWithPlan extends IPlanVersion {
     plan: IPlan;
 }
+/**
+ * Plan group version with full plan versions (for GET .../plan-group/versions).
+ * Each plan has plan, subscriptionItems, quotas (per-interval), pricingVariants.
+ */
 interface IPlanGroupVersionWithPlans {
     _id: string;
     version: number;
     description?: string;
+    /** Full plan versions with nested plan (name, slug, currency). */
     plans: IPlanVersionWithPlan[];
     isCurrent?: boolean;
     whatsNew?: {
@@ -160,24 +223,35 @@ 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. May be null in some API responses. */
+    group: IPlanGroup | null;
+    /** Current group version with populated planVersionIds (or IDs). */
+    groupVersion: IPlanGroupVersion;
+    /** Full plan versions for display (subscriptionItems, pricingVariants, quotas). */
+    plans: IPlanVersionWithPlan[];
 }
+/**
+ * Response from GET workspaces/:workspaceId/subscription/plan-group/versions.
+ * Group summary plus current and available group versions; each version has plans with
+ * per-interval quotas and pricingVariants.
+ */
 interface IPlanGroupVersionsResponse {
-    group: {
-        _id: string;
-        name: string;
-        slug: string;
-    };
+    /** Plan group summary (_id, name, slug). */
+    group: IPlanGroupInfo;
+    /** Current group version (user's version when subscribed, or latest published when not). */
     currentVersion: IPlanGroupVersionWithPlans;
+    /** Newer versions when user has subscription; empty when no subscription. */
     availableVersions: IPlanGroupVersionWithPlans[];
 }
+/** Request body for POST .../workspaces/:id/subscription/checkout. Only these fields are allowed. */
 interface ICheckoutSessionRequest {
     planVersionId: string;
     billingInterval?: BillingInterval;
@@ -195,6 +269,7 @@ interface ICheckoutSessionResponse {
         name: string;
     };
 }
+/** Request body for PATCH .../workspaces/:id/subscription. Only these fields are allowed. */
 interface ISubscriptionUpdateRequest {
     planVersionId: string;
     billingInterval?: BillingInterval;
@@ -221,33 +296,33 @@ interface IPublicPlanItem {
     _id: string;
     name: string;
     slug: string;
-    description: string;
+    description?: string;
     type: 'feature' | 'limit' | 'quota';
     category: IPublicPlanItemCategory;
 }
-interface IPublicPlanPricing {
-    monthly: number;
-    yearly: number;
-    quarterly: number;
-}
-interface IPublicPlanQuotaValue {
-    included: number;
-    overage: number;
-    stripePriceId?: string;
-}
+/**
+ * Public plan version (e.g. from GET /api/v1/public/:orgId/plans/:slug).
+ * Each plan has _id, name (plan display name), version, status, pricingVariants, quotas, features, limits.
+ * Pricing is in cents (see response.notes).
+ */
 interface IPublicPlanVersion {
     _id: string;
+    /** Plan display name (e.g. "Pro", "Base Plan"). */
     name: string;
     version: number;
     status: 'draft' | 'published';
-    pricing: IPublicPlanPricing;
-    quotas: Record<string, IPublicPlanQuotaValue>;
+    /** Multi-currency pricing. Use getBasePriceCents(plan, currency, interval) and getQuotaDisplayWithVariant for display. */
+    pricingVariants?: IPricingVariant[];
+    /** Keyed by item slug. Per-interval: included, unitSize; overage from pricingVariant.quotaOverages. */
+    quotas: Record<string, IQuotaByInterval>;
     features: Record<string, boolean>;
     limits: Record<string, number>;
 }
 interface IPublicPlansResponse {
     items: IPublicPlanItem[];
     plans: IPublicPlanVersion[];
+    /** Optional note from API (e.g. "Pricing is in cents. Please convert to dollars for display."). */
+    notes?: string;
 }
 type InvoiceStatus = 'draft' | 'open' | 'paid' | 'uncollectible' | 'void';
 interface IInvoice {
@@ -283,7 +358,24 @@ interface IWorkspace {
     roles: string[];
     createdBy: string | IUser;
     features: Record<string, boolean>;
-    subscription?: ISubscription | null;
+    /**
+     * Quota usage tracking: { [quotaSlug]: number } – how much of each quota has been used.
+     */
+    quotas?: Record<string, number>;
+    /**
+     * Subscription limits snapshot: { [limitSlug]: number | null } – synced from subscription plan.
+     * Limits are maximum values (e.g. max-users, max-workspaces). Updated when subscription is assigned/updated.
+     */
+    limits?: Record<string, number | null>;
+    subscription?: ISubscription | string | null;
+    /** Stripe Customer ID for this workspace. */
+    stripeCustomerId?: string;
+    /**
+     * Billing currency locked for this workspace (set on first subscription).
+     * Stripe allows one currency per customer; all future subscriptions must use this currency.
+     * When set, subscription UI only shows/uses this currency.
+     */
+    billingCurrency?: string | null;
 }
 interface IWorkspaceFeature {
     _id: string;
@@ -477,6 +569,8 @@ interface PricingPageDetails {
     items: IPublicPlanItem[];
     /** Plan versions with pricing, features, limits, quotas */
     plans: IPublicPlanVersion[];
+    /** Optional note from API (e.g. "Pricing is in cents. Please convert to dollars for display.") */
+    notes?: string;
     /** Refetch plan data */
     refetch: () => Promise<void>;
 }
@@ -512,7 +606,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;
@@ -780,69 +874,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>;
@@ -855,6 +1029,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.
@@ -910,6 +1089,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.
@@ -990,111 +1231,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;
@@ -1110,7 +1371,7 @@ declare const useSaaSWorkspaces: () => {
         forceEmit?: boolean;
     }) => Promise<void>;
     resetCurrentWorkspace: () => void;
-    createWorkspace: (name: string, image: string) => Promise<void>;
+    createWorkspace: (name: string, image?: string) => Promise<void>;
     allFeatures: IWorkspaceFeature[];
     getFeatures: () => Promise<IWorkspaceFeature[] | null>;
     updateFeature: (workspaceId: string, key: string, value: boolean) => Promise<IWorkspace>;
@@ -1138,6 +1399,7 @@ declare const useSaaSWorkspaces: () => {
         success: boolean;
     }>;
     switching: boolean;
+    switchingToId: string | null;
 };
 
 declare function WorkspaceSwitcher(props: {
@@ -1155,6 +1417,7 @@ declare function WorkspaceSwitcher(props: {
 declare const usePublicPlans: (slug: string) => {
     items: IPublicPlanItem[];
     plans: IPublicPlanVersion[];
+    notes: string | undefined;
     loading: boolean;
     error: string | null;
     refetch: () => Promise<void>;
@@ -1265,7 +1528,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} />
  *       ))}
@@ -1705,5 +1968,138 @@ 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>;
+}
+
+/**
+ * Centralized formatting for subscription/quota display: cents, overage rates, included + overage text.
+ * Currency must be provided by the caller (e.g. workspace.billingCurrency, plan.currency, or selected currency).
+ */
+/** Common currency display (code or symbol). Use lowercase Stripe codes (usd, eur, etc.). */
+declare const CURRENCY_DISPLAY: Record<string, string>;
+/** Currency code to flag emoji (country/region associated with the currency). Use for dropdowns. */
+declare const CURRENCY_FLAG: Record<string, string>;
+/** Get flag emoji for a currency code. Returns empty string when unknown or empty. */
+declare function getCurrencyFlag(currency: string): string;
+/** Get currency symbol for display. Use lowercase Stripe codes (usd, eur). Returns code when unknown; empty string when currency is empty. */
+declare function getCurrencySymbol(currency: string): string;
+/** Allowed plan/pricing currency codes (must match server ALLOWED_BILLING_CURRENCIES). Use for dropdowns and validation. */
+declare const PLAN_CURRENCY_CODES: readonly ["usd", "eur", "gbp", "jpy", "cad", "aud", "chf", "cny", "hkd", "sgd", "inr", "mxn", "brl", "nzd", "sek", "nok", "dkk", "pln", "thb"];
+/** Options for plan currency select: { value, label } with symbol. Use in CreateOrEditPlan and anywhere a currency dropdown is needed. */
+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;
+}[];
+/** Format cents as money string (e.g. 1999, "usd" -> "$19.99"). Caller must pass currency (e.g. from plan or workspace). */
+declare function formatCents(cents: number, currency: string): string;
+/**
+ * Format overage rate for display. When unitSize > 1: "$1.00/1,000 units"; else "$1.00/unit".
+ * Returns null if overageCents is missing or negative.
+ */
+declare function formatOverageRate(overageCents: number | undefined, unitSize: number | undefined, currency: string): string | null;
+/**
+ * Format overage rate with optional unit label for comparison/preview UIs.
+ * e.g. formatOverageRateWithLabel(50, 1000, "video") -> "$0.50/1,000 videos"
+ *      formatOverageRateWithLabel(46, 1, "video") -> "$0.46/video"
+ * When unitLabel is omitted, falls back to formatOverageRate behavior.
+ */
+declare function formatOverageRateWithLabel(overageCents: number | undefined, unitSize: number | undefined, unitLabel: string | undefined, currency: 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.
+ */
+declare function getQuotaUnitLabelFromName(nameOrSlug: string): string;
+/**
+ * Format quota "included + overage" for display.
+ * When unitSize >= 2: "Included: 1,000, after that $1.00/1,000 emails".
+ * Otherwise: "Included: 5, after that $0.30/image".
+ */
+declare function formatQuotaIncludedOverage(included: number | undefined, overageCents: number | undefined, unitLabel: string, currency: string, unitSize?: number): string;
+
+/**
+ * Helpers for multi-currency plan version pricing (pricingVariants).
+ */
+
+/** Get the pricing variant for a currency, or null if not available. */
+declare function getPricingVariant(planVersion: IPlanVersion, currency: string): IPricingVariant | null;
+/**
+ * Get base price in cents for a plan version and currency/interval.
+ */
+declare function getBasePriceCents(planVersion: IPlanVersion, currency: string, interval: BillingInterval): number | null;
+/**
+ * Get Stripe price ID for the given plan version, currency, and interval.
+ */
+declare function getStripePriceIdForInterval(planVersion: IPlanVersion, currency: string, interval: BillingInterval): string | null;
+/**
+ * Get overage amount in cents for a quota in a given currency and interval.
+ * Returns undefined if not defined in the pricing variant.
+ */
+declare function getQuotaOverageCents(planVersion: IPlanVersion, currency: string, quotaSlug: string, interval: BillingInterval): number | undefined;
+/**
+ * Get display currency for a plan version when using a given currency.
+ * Returns the requested currency if the variant exists; otherwise plan.currency or null.
+ */
+declare function getDisplayCurrency(planVersion: IPlanVersionWithPlan, currency: string): string;
+/** Minimal shape for extracting currencies (IPlanVersionWithPlan or IPublicPlanVersion). */
+type PlanVersionWithPricingVariants = {
+    pricingVariants?: IPricingVariant[];
+};
+/**
+ * Collect all unique currency codes from plan versions (from their pricingVariants).
+ * Use for currency selector. Accepts IPlanVersionWithPlan[] or IPublicPlanVersion[].
+ */
+declare function getAvailableCurrenciesFromPlans(planVersions: PlanVersionWithPricingVariants[]): string[];
+/**
+ * Quota display shape: included count and optional overage (cents) and unitSize from plan + variant.
+ */
+type QuotaDisplayWithOverage = {
+    included: number;
+    overage?: number;
+    unitSize?: number;
+} | null;
+/**
+ * Get quota display value for a slug/interval, merging plan version quotas (included, unitSize)
+ * with pricing variant overage (cents) when available.
+ */
+declare function getQuotaDisplayWithVariant(planVersion: IPlanVersion, currency: string, quotaSlug: string, interval: BillingInterval): QuotaDisplayWithOverage;
+/**
+ * Resolve billing interval and currency from a Stripe price ID by checking all plan versions' pricingVariants.
+ */
+declare function getBillingIntervalAndCurrencyFromPriceId(priceId: string | null | undefined, planVersions: IPlanVersionWithPlan[]): {
+    interval: BillingInterval;
+    currency: string;
+} | null;
+
+type QuotaDisplayValue = {
+    included: number;
+    overage?: number;
+    unitSize?: number;
+} | null;
+/**
+ * Normalize a per-interval quota value to a display shape for the given billing interval.
+ */
+declare function getQuotaDisplayValue(value: 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 override. When omitted, derived from `currency` (empty if no currency). */
+    currencySymbol?: string;
+    /** Stripe currency code (e.g. 'usd', 'inr'). Used to resolve symbol when currencySymbol is not set. */
+    currency?: 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, CURRENCY_DISPLAY, CURRENCY_FLAG, PLAN_CURRENCY_CODES, PLAN_CURRENCY_OPTIONS, PricingPage, SaaSOSProvider, SettingsApi, SubscriptionContextProvider, UserApi, WhenAuthenticated, WhenNoSubscription, WhenRoles, WhenSubscription, WhenSubscriptionToPlans, WhenUnauthenticated, WhenUserFeatureDisabled, WhenUserFeatureEnabled, WhenWorkspaceFeatureDisabled, WhenWorkspaceFeatureEnabled, WhenWorkspaceRoles, WorkspaceApi, WorkspaceSwitcher, eventEmitter, formatCents, formatOverageRate, formatOverageRateWithLabel, formatQuotaIncludedOverage, formatQuotaWithPrice, getAvailableCurrenciesFromPlans, getBasePriceCents, getBillingIntervalAndCurrencyFromPriceId, getCurrencyFlag, getCurrencySymbol, getDisplayCurrency, getPricingVariant, getQuotaDisplayValue, getQuotaDisplayWithVariant, getQuotaOverageCents, getQuotaUnitLabelFromName, getStripePriceIdForInterval, 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, IPricingVariant, IPublicPlanItem, IPublicPlanItemCategory, IPublicPlanVersion, IPublicPlansResponse, IQuotaByInterval, IQuotaIntervalValue, IQuotaOveragePriceIdsByInterval, IQuotaOveragesByInterval, IStripePricesByInterval, ISubscription, ISubscriptionItem, ISubscriptionResponse, ISubscriptionUpdateRequest, ISubscriptionUpdateResponse, InvoiceStatus, OnWorkspaceChangeParams, PlanVersionWithPricingVariants, PricingPageDetails, PricingPageProps, QuotaDisplayValue, QuotaDisplayWithOverage, SubscriptionContextValue, UserCreatedEventData, UserUpdatedEventData, WorkspaceChangedEventData, WorkspaceCreatedEventData, WorkspaceDeletedEventData, WorkspaceUpdatedEventData, WorkspaceUserAddedEventData, WorkspaceUserRemovedEventData, WorkspaceUserRoleChangedEventData };