@buildbase/sdk 0.0.21 → 0.0.22

package/README.md

@@ -36,6 +36,7 @@ A React SDK for [BuildBase](https://www.buildbase.app/) that provides essential
 - **🎯 Feature Flags** - Workspace-level and user-level feature toggles
 - **📋 Subscription Gates** - Show or hide UI based on current workspace subscription (plan)
 - **📊 Quota Usage Tracking** - Record and monitor metered usage (API calls, storage, etc.) with real-time status
+- **📈 Usage Dashboard** - Built-in workspace settings page showing quota consumption, overage billing breakdowns, and billing period info
 - **👤 User Management** - User attributes and feature flags management
 - **📝 Beta Form** - Pre-built signup/waitlist form component
 - **📡 Event System** - Subscribe to user and workspace events
@@ -224,10 +225,24 @@ const {
   status, // AuthStatus: 'loading' | 'redirecting' | 'authenticating' | 'authenticated' | 'unauthenticated' (use AuthStatus enum for type-safe checks)
   signIn, // Function: initiates sign-in flow
   signOut, // Function: signs out the user
-  openWorkspaceSettings, // Function: opens workspace settings dialog
+  openWorkspaceSettings, // Function: opens workspace settings dialog to a specific section
 } = useSaaSAuth();
 ```
 
+#### Workspace Settings Sections
+
+Open the workspace settings dialog to a specific section:
+
+```tsx
+openWorkspaceSettings('profile');      // Account profile
+openWorkspaceSettings('general');      // Workspace name, icon
+openWorkspaceSettings('users');        // Workspace members
+openWorkspaceSettings('subscription'); // Plan & Billing
+openWorkspaceSettings('usage');        // Quota usage dashboard
+openWorkspaceSettings('features');     // Feature toggles
+openWorkspaceSettings('danger');       // Delete workspace (owner only)
+```
+
 ### Authentication Components
 
 For declarative rendering, use the conditional components:
@@ -1188,9 +1203,10 @@ Prefer these SDK hooks for state and operations instead of `useAppSelector`:
 | `useUserAttributes()`      | User attributes and update/refresh                                                                      |
 | `useUserFeatures()`        | User feature flags                                                                                      |
 | `useSubscriptionContext()` | Subscription for current workspace (response, loading, refetch); use inside SubscriptionContextProvider |
-| Subscription hooks         | `usePublicPlans`, `useSubscription`, `usePlanGroup`, `useCreateCheckoutSession`, `useUpdateSubscription`, `useCancelSubscription`, `useResumeSubscription`, `useInvoices`, `useInvoice` |
+| Subscription hooks         | `usePublicPlans`, `useSubscription`, `useSubscriptionManagement`, `usePlanGroup`, `usePlanGroupVersions`, `usePublicPlanGroupVersion`, `useCreateCheckoutSession`, `useUpdateSubscription`, `useCancelSubscription`, `useResumeSubscription`, `useInvoices`, `useInvoice` |
 | `useQuotaUsageContext()`   | Quota usage for current workspace (quotas, loading, refetch); use inside QuotaUsageContextProvider      |
 | Quota usage hooks          | `useRecordUsage`, `useQuotaUsageStatus`, `useAllQuotaUsage`, `useUsageLogs`                             |
+| Invalidation helpers       | `invalidateSubscription()`, `invalidateQuotaUsage()` — trigger context refetch after server-side mutations |
 
 Using hooks keeps your code stable if internal state shape changes and avoids direct Redux/context coupling.
 

package/dist/index.d.ts

@@ -30,11 +30,23 @@ interface IUser extends IDocument {
 type BillingInterval = 'monthly' | 'yearly' | 'quarterly';
 interface ISubscription {
     _id: string;
-    subscriptionStatus: 'active' | 'trialing' | 'canceled' | 'past_due';
+    subscriptionStatus: 'active' | 'trialing' | 'canceled' | 'past_due' | 'paused' | 'incomplete' | 'unpaid';
     stripePriceId?: string;
     stripeCurrentPeriodEnd?: string;
     cancelAtPeriodEnd: boolean;
     billingInterval?: BillingInterval;
+    /** Trial start date (ISO string). Set when subscription is in trial. */
+    trialStart?: string;
+    /** Trial end date (ISO string). Set when subscription is in trial. */
+    trialEnd?: string;
+    /** When the subscription was canceled (ISO string). Soft-delete marker. */
+    canceledAt?: string;
+    /** Dunning state: 'none', 'notified', 'warning', 'final', 'suspended'. */
+    dunningState?: string;
+    /** Whether this subscription uses per-seat pricing. */
+    seatPricingEnabled?: boolean;
+    /** Current billable seat count. */
+    currentSeatCount?: number;
     createdAt: string;
     updatedAt: string;
     plan?: {
@@ -105,6 +117,16 @@ interface IPricingVariant {
     currency: string;
     basePricing: IBasePricing;
     stripePrices: IStripePricesByInterval;
+    /** Per-seat pricing config. When enabled, a second recurring item is on the subscription. */
+    seatPricing?: {
+        enabled: boolean;
+        includedSeats: number;
+        /** Maximum seats allowed. 0 or undefined = unlimited. */
+        maxSeats?: number;
+        perSeat: IBasePricing;
+    };
+    /** Stripe Price IDs for the per-seat recurring price. */
+    seatStripePrices?: IStripePricesByInterval;
     /** Overage cents per quota slug per interval. */
     quotaOverages?: IQuotaOveragesByInterval;
     /** Stripe price IDs for overage per quota slug per interval. */
@@ -260,6 +282,8 @@ interface ICheckoutSessionRequest {
     cancelUrl?: string;
 }
 interface ICheckoutSessionResponse {
+    /** Response type discriminator. Added for centralized checkout flow. */
+    type?: 'checkout' | 'trial_started' | 'existing';
     success: boolean;
     checkoutUrl: string;
     sessionId: string;
@@ -270,6 +294,37 @@ interface ICheckoutSessionResponse {
         name: string;
     };
 }
+/** No-card trial started server-side; no redirect needed. */
+interface ICheckoutTrialResult {
+    type: 'trial_started';
+    success: boolean;
+    checkoutUrl: null;
+    sessionId: null;
+    subscription: ISubscription;
+    message: string;
+}
+/** Workspace already has a matching active subscription. */
+interface ICheckoutExistingResult {
+    type: 'existing';
+    success: boolean;
+    checkoutUrl: null;
+    sessionId: null;
+    message: string;
+    existingSubscription?: {
+        _id: string;
+        subscriptionStatus: string;
+        stripePriceId?: string;
+    };
+}
+/**
+ * Discriminated union for POST /subscription/checkout responses.
+ * - `checkout`: Stripe checkout session created, redirect user to checkoutUrl
+ * - `trial_started`: No-card trial started server-side, no redirect needed
+ * - `existing`: Workspace already has a matching subscription
+ */
+type CheckoutResult = (ICheckoutSessionResponse & {
+    type: 'checkout';
+}) | ICheckoutTrialResult | ICheckoutExistingResult;
 /** Request body for PATCH .../workspaces/:id/subscription. Only these fields are allowed. */
 interface ISubscriptionUpdateRequest {
     planVersionId: string;
@@ -439,6 +494,11 @@ interface IWorkspace {
      * When set, subscription UI only shows/uses this currency.
      */
     billingCurrency?: string | null;
+    /** Workspace onboarding config. Set on creation based on org settings. SDK shows trial CTA. */
+    pendingOnboarding?: {
+        mode: 'trial';
+        planVersionId: string;
+    } | null;
 }
 interface IWorkspaceFeature {
     _id: string;
@@ -1077,6 +1137,71 @@ declare const WhenSubscriptionToPlans: {
     (props: IWhenSubscriptionToPlansProps): react.ReactNode;
     displayName: string;
 };
+interface IWhenTrialingProps {
+    /** Content to render when the condition is met. */
+    children: React.ReactNode;
+    /** Optional component/element to show while subscription is loading. */
+    loadingComponent?: React.ReactNode;
+    /** Optional component/element to show when condition is not met. */
+    fallbackComponent?: React.ReactNode;
+}
+/**
+ * Renders children only when the current workspace subscription is in trial (status === 'trialing').
+ * Must be used within SubscriptionContextProvider.
+ *
+ * @example
+ * ```tsx
+ * <WhenTrialing fallbackComponent={<NormalContent />}>
+ *   <TrialBanner />
+ * </WhenTrialing>
+ * ```
+ */
+declare const WhenTrialing: {
+    (props: IWhenTrialingProps): react.ReactNode;
+    displayName: string;
+};
+/**
+ * Renders children only when the current workspace subscription is NOT in trial.
+ * This includes: no subscription, active, canceled, past_due, etc.
+ * Must be used within SubscriptionContextProvider.
+ *
+ * @example
+ * ```tsx
+ * <WhenNotTrialing>
+ *   <RegularPricingPage />
+ * </WhenNotTrialing>
+ * ```
+ */
+declare const WhenNotTrialing: {
+    (props: IWhenTrialingProps): react.ReactNode;
+    displayName: string;
+};
+interface IWhenTrialEndingProps {
+    /** Content to render when trial is ending soon. */
+    children: React.ReactNode;
+    /** Optional component/element to show while subscription is loading. */
+    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. */
+    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.
+ * Must be used within SubscriptionContextProvider.
+ *
+ * @example
+ * ```tsx
+ * <WhenTrialEnding daysThreshold={5}>
+ *   <UpgradeBanner />
+ * </WhenTrialEnding>
+ * ```
+ */
+declare const WhenTrialEnding: {
+    (props: IWhenTrialEndingProps): react.ReactNode;
+    displayName: string;
+};
 
 interface IWhenQuotaProps {
     /** Quota slug to check (e.g. 'api_calls', 'emails', 'storage'). */
@@ -1584,7 +1709,7 @@ declare class WorkspaceApi extends BaseApi {
      * @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>;
+    createCheckoutSession(workspaceId: string, request: ICheckoutSessionRequest): Promise<CheckoutResult>;
     /**
      * Update subscription (upgrade/downgrade)
      * Only allows plan changes within the same plan group
@@ -1945,7 +2070,7 @@ declare const usePlanGroupVersions: (workspaceId: string | null | undefined) =>
  * ```
  */
 declare const useCreateCheckoutSession: (workspaceId: string | null | undefined) => {
-    createCheckoutSession: (request: ICheckoutSessionRequest) => Promise<ICheckoutSessionResponse>;
+    createCheckoutSession: (request: ICheckoutSessionRequest) => Promise<CheckoutResult>;
     loading: boolean;
     error: string | null;
 };
@@ -2440,6 +2565,78 @@ declare const useUsageLogs: (workspaceId: string | null | undefined, quotaSlug?:
     refetch: () => Promise<void>;
 };
 
+interface TrialStatus {
+    /** Whether the current subscription is in trial. */
+    isTrialing: boolean;
+    /** Number of days remaining in the trial. 0 if not trialing or expired. */
+    daysRemaining: number;
+    /** Trial end date as a Date object. null if not trialing. */
+    trialEndsAt: Date | null;
+    /** Trial start date as a Date object. null if not trialing. */
+    trialStartedAt: Date | null;
+    /** Whether the trial is ending soon (<= 3 days remaining). */
+    isTrialEnding: boolean;
+}
+/**
+ * Hook that computes trial status from the current subscription context.
+ * Must be used within SubscriptionContextProvider.
+ *
+ * @returns TrialStatus — computed trial information
+ *
+ * @example
+ * ```tsx
+ * const { isTrialing, daysRemaining, isTrialEnding } = useTrialStatus();
+ *
+ * if (isTrialEnding) {
+ *   return <UpgradeBanner daysLeft={daysRemaining} />;
+ * }
+ * ```
+ */
+declare function useTrialStatus(): TrialStatus;
+
+interface SeatStatus {
+    /** Whether the current plan uses seat-based pricing. */
+    hasSeatPricing: boolean;
+    /** Total workspace members. */
+    memberCount: number;
+    /** Seats included in the base price (free). */
+    includedSeats: number;
+    /** Maximum seats allowed. 0 = unlimited. */
+    maxSeats: number;
+    /** Seats beyond included that are being billed. */
+    billableSeats: number;
+    /** Remaining seats before hitting max. Infinity if unlimited. */
+    availableSeats: number;
+    /** Whether workspace is at max seat capacity. */
+    isAtMax: boolean;
+    /** Whether workspace is near max (>= 80% used). */
+    isNearMax: boolean;
+    /** Per-seat price in cents for the current billing interval. Null if not applicable. */
+    perSeatPriceCents: number | null;
+    /** Billing currency. */
+    currency: string;
+}
+/**
+ * Hook that computes seat status from subscription context and workspace data.
+ * Must be used within SubscriptionContextProvider.
+ *
+ * @param workspace - The current workspace (needs users array)
+ * @returns SeatStatus — computed seat information
+ *
+ * @example
+ * ```tsx
+ * const { isAtMax, availableSeats, billableSeats } = useSeatStatus(workspace);
+ *
+ * if (isAtMax) {
+ *   return <UpgradeBanner />;
+ * }
+ * ```
+ */
+declare function useSeatStatus(workspace: {
+    users?: any[];
+    billingCurrency?: string | null;
+} | null): SeatStatus;
+
 /**
  * EventEmitter class to handle and trigger event callbacks
  * This class manages all event listeners and provides methods to trigger events
@@ -2627,6 +2824,19 @@ declare function getBillingIntervalAndCurrencyFromPriceId(priceId: string | null
     interval: BillingInterval;
     currency: string;
 } | null;
+/** Get per-seat pricing config for a plan version and currency. Null if not enabled. */
+declare function getSeatPricing(planVersion: IPlanVersion, currency: string): IPricingVariant['seatPricing'] | null;
+/** Get per-seat price in cents for a billing interval. Null if seat pricing not enabled. */
+declare function getPerSeatPriceCents(planVersion: IPlanVersion, currency: string, interval: BillingInterval): number | null;
+/** Calculate billable seats: max(0, currentSeats - includedSeats). */
+declare function calculateBillableSeats(currentSeatCount: number, includedSeats: number): number;
+/** Calculate total seat overage cost in cents. Null if seat pricing not enabled. */
+declare function calculateSeatOverageCents(planVersion: IPlanVersion, currency: string, interval: BillingInterval, currentSeatCount: number): number | null;
+/**
+ * Calculate total subscription price in cents: base + seat overage (if enabled).
+ * Does not include metered usage (billed at period end).
+ */
+declare function calculateTotalSubscriptionCents(planVersion: IPlanVersion, currency: string, interval: BillingInterval, currentSeatCount?: number): number | null;
 
 type QuotaDisplayValue = {
     included: number;
@@ -2652,5 +2862,5 @@ interface FormatQuotaWithPriceOptions {
  */
 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, QuotaUsageContextProvider, SaaSOSProvider, SettingsApi, SubscriptionContextProvider, UserApi, WhenAuthenticated, WhenNoSubscription, WhenQuotaAvailable, WhenQuotaExhausted, WhenQuotaOverage, WhenQuotaThreshold, 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, invalidateQuotaUsage, invalidateSubscription, useAllQuotaUsage, useCancelSubscription, useCreateCheckoutSession, useInvoice, useInvoices, usePlanGroup, usePlanGroupVersions, usePublicPlanGroupVersion, usePublicPlans, useQuotaUsageContext, useQuotaUsageStatus, useRecordUsage, useResumeSubscription, useSaaSAuth, useSaaSOs, useSaaSSettings, useSaaSWorkspaces, useSubscription, useSubscriptionContext, useSubscriptionManagement, useUpdateSubscription, useUsageLogs, useUserAttributes, useUserFeatures };
-export type { BillingInterval, EventData, EventType, FormatQuotaWithPriceOptions, IAllQuotaUsageResponse, 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, IQuotaUsageStatus, IQuotaUsageStatusResponse, IRecordUsageRequest, IRecordUsageResponse, IStripePricesByInterval, ISubscription, ISubscriptionItem, ISubscriptionResponse, ISubscriptionUpdateRequest, ISubscriptionUpdateResponse, IUsageLogEntry, IUsageLogsQuery, IUsageLogsResponse, InvoiceStatus, OnWorkspaceChangeParams, PlanVersionWithPricingVariants, PricingPageDetails, PricingPageProps, QuotaDisplayValue, QuotaDisplayWithOverage, QuotaUsageContextValue, SubscriptionContextValue, UserCreatedEventData, UserUpdatedEventData, WorkspaceChangedEventData, WorkspaceCreatedEventData, WorkspaceDeletedEventData, WorkspaceUpdatedEventData, WorkspaceUserAddedEventData, WorkspaceUserRemovedEventData, WorkspaceUserRoleChangedEventData };
+export { ApiVersion, AuthStatus, BaseApi, BetaForm, CURRENCY_DISPLAY, CURRENCY_FLAG, PLAN_CURRENCY_CODES, PLAN_CURRENCY_OPTIONS, PricingPage, QuotaUsageContextProvider, SaaSOSProvider, SettingsApi, SubscriptionContextProvider, UserApi, WhenAuthenticated, WhenNoSubscription, WhenNotTrialing, WhenQuotaAvailable, WhenQuotaExhausted, WhenQuotaOverage, WhenQuotaThreshold, WhenRoles, WhenSubscription, WhenSubscriptionToPlans, WhenTrialEnding, WhenTrialing, WhenUnauthenticated, WhenUserFeatureDisabled, WhenUserFeatureEnabled, WhenWorkspaceFeatureDisabled, WhenWorkspaceFeatureEnabled, WhenWorkspaceRoles, WorkspaceApi, WorkspaceSwitcher, calculateBillableSeats, calculateSeatOverageCents, calculateTotalSubscriptionCents, eventEmitter, formatCents, formatOverageRate, formatOverageRateWithLabel, formatQuotaIncludedOverage, formatQuotaWithPrice, getAvailableCurrenciesFromPlans, getBasePriceCents, getBillingIntervalAndCurrencyFromPriceId, getCurrencyFlag, getCurrencySymbol, getDisplayCurrency, getPerSeatPriceCents, getPricingVariant, getQuotaDisplayValue, getQuotaDisplayWithVariant, getQuotaOverageCents, getQuotaUnitLabelFromName, getSeatPricing, getStripePriceIdForInterval, invalidateQuotaUsage, invalidateSubscription, useAllQuotaUsage, useCancelSubscription, useCreateCheckoutSession, useInvoice, useInvoices, usePlanGroup, usePlanGroupVersions, usePublicPlanGroupVersion, usePublicPlans, useQuotaUsageContext, useQuotaUsageStatus, useRecordUsage, useResumeSubscription, useSaaSAuth, useSaaSOs, useSaaSSettings, useSaaSWorkspaces, useSeatStatus, useSubscription, useSubscriptionContext, useSubscriptionManagement, useTrialStatus, useUpdateSubscription, useUsageLogs, useUserAttributes, useUserFeatures };
+export type { BillingInterval, CheckoutResult, EventData, EventType, FormatQuotaWithPriceOptions, IAllQuotaUsageResponse, 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, IQuotaUsageStatus, IQuotaUsageStatusResponse, IRecordUsageRequest, IRecordUsageResponse, IStripePricesByInterval, ISubscription, ISubscriptionItem, ISubscriptionResponse, ISubscriptionUpdateRequest, ISubscriptionUpdateResponse, IUsageLogEntry, IUsageLogsQuery, IUsageLogsResponse, InvoiceStatus, OnWorkspaceChangeParams, PlanVersionWithPricingVariants, PricingPageDetails, PricingPageProps, QuotaDisplayValue, QuotaDisplayWithOverage, QuotaUsageContextValue, SeatStatus, SubscriptionContextValue, TrialStatus, UserCreatedEventData, UserUpdatedEventData, WorkspaceChangedEventData, WorkspaceCreatedEventData, WorkspaceDeletedEventData, WorkspaceUpdatedEventData, WorkspaceUserAddedEventData, WorkspaceUserRemovedEventData, WorkspaceUserRoleChangedEventData };