@buildbase/sdk 0.0.27 → 0.0.28

package/dist/index.d.ts

@@ -2619,6 +2619,116 @@ interface TrialStatus {
  */
 declare function useTrialStatus(): TrialStatus;
 
+/**
+ * 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;
+/** 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;
+interface MaxUsersConfig {
+    /** The resolved maximum number of users allowed. 0 = unlimited. */
+    maxUsers: number;
+    /** Where the limit comes from. */
+    source: 'seat_pricing' | 'settings' | 'none';
+    /** Seats included in the base plan price (0 if no seat pricing). */
+    includedSeats: number;
+    /** Whether seat-based pricing is active. */
+    hasSeatPricing: boolean;
+}
+/**
+ * Resolve the effective max users limit from the plan's seat pricing config,
+ * falling back to settings when no seat pricing is configured.
+ *
+ * Priority:
+ * 1. Seat pricing `maxSeats` (from plan version's pricing variant) — the plan controls the limit
+ * 2. Settings fallback (`workspace.maxWorkspaceUsers`) — for workspaces without a subscription
+ *
+ * Returns 0 if no limit is set (unlimited).
+ */
+declare function resolveMaxUsers(opts: {
+    planVersion?: IPlanVersion | null;
+    currency?: string;
+    settingsMaxUsers?: number | null;
+}): MaxUsersConfig;
+type InviteBlockReason = 'seat_limit_reached' | 'settings_user_limit_reached' | 'no_subscription' | null;
+interface InviteValidation {
+    /** Whether a new user can be invited. */
+    canInvite: boolean;
+    /** Reason the invite is blocked, or null if allowed. */
+    blockReason: InviteBlockReason;
+    /** Human-readable message for the block reason. */
+    blockMessage: string | null;
+}
+/**
+ * Validate whether a new member can be invited given current seat/user limits.
+ */
+declare function validateInvite(opts: {
+    memberCount: number;
+    maxUsersConfig: MaxUsersConfig;
+    hasSubscription?: boolean;
+    requireSubscription?: boolean;
+}): InviteValidation;
+
 interface SeatStatus {
     /** Whether the current plan uses seat-based pricing. */
     hasSeatPricing: boolean;
@@ -2626,13 +2736,20 @@ interface SeatStatus {
     memberCount: number;
     /** Seats included in the base price (free). */
     includedSeats: number;
-    /** Maximum seats allowed. 0 = unlimited. */
+    /** Maximum users allowed (resolved from seat pricing, plan limits, or settings). 0 = unlimited. */
+    maxUsers: number;
+    /**
+     * Maximum seats allowed from seat pricing config. 0 = unlimited.
+     * @deprecated Use `maxUsers` for the unified limit.
+     */
     maxSeats: number;
+    /** Where the max user limit comes from. */
+    limitSource: MaxUsersConfig['source'];
     /** 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. */
+    /** Whether workspace is at max seat/user capacity. */
     isAtMax: boolean;
     /** Whether workspace is near max (>= 80% used). */
     isNearMax: boolean;
@@ -2640,27 +2757,37 @@ interface SeatStatus {
     perSeatPriceCents: number | null;
     /** Billing currency. */
     currency: string;
+    /** Whether a new member can be invited. */
+    canInvite: boolean;
+    /** Reason the invite is blocked, or null if allowed. */
+    inviteBlockReason: InviteBlockReason;
+    /** Human-readable message for why invite is blocked. */
+    inviteBlockMessage: string | null;
 }
 /**
  * Hook that computes seat status from subscription context and workspace data.
+ * Resolves max user limits from seat pricing, plan limits, and settings in priority order.
  * Must be used within SubscriptionContextProvider.
  *
- * @param workspace - The current workspace (needs users array)
- * @returns SeatStatus — computed seat information
+ * @param workspace - The current workspace (needs users array, limits, billingCurrency)
+ * @param options - Optional overrides (e.g. settingsMaxUsers fallback)
+ * @returns SeatStatus — computed seat and invite information
  *
  * @example
  * ```tsx
- * const { isAtMax, availableSeats, billableSeats } = useSeatStatus(workspace);
+ * const { isAtMax, canInvite, inviteBlockMessage, availableSeats } = useSeatStatus(workspace);
  *
- * if (isAtMax) {
- *   return <UpgradeBanner />;
+ * if (!canInvite) {
+ *   return <div>{inviteBlockMessage}</div>;
  * }
  * ```
  */
 declare function useSeatStatus(workspace: {
     users?: any[];
     billingCurrency?: string | null;
-} | null): SeatStatus;
+} | null, options?: {
+    settingsMaxUsers?: number | null;
+}): SeatStatus;
 
 interface PushNotificationState {
     /** Browser's Notification.permission: 'default' | 'granted' | 'denied' */
@@ -2846,73 +2973,6 @@ declare function getQuotaUnitLabelFromName(nameOrSlug: string): string;
  */
 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;
-/** 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;
     overage?: number;
@@ -2937,5 +2997,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, PUSH_SERVICE_WORKER_SCRIPT, PricingPage, PushNotificationProvider, 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, useBillingPortal, useCancelSubscription, useCreateCheckoutSession, useInvoice, useInvoices, usePlanGroup, usePlanGroupVersions, usePublicPlanGroupVersion, usePublicPlans, usePushNotifications, 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 };
+export { ApiVersion, AuthStatus, BaseApi, BetaForm, CURRENCY_DISPLAY, CURRENCY_FLAG, PLAN_CURRENCY_CODES, PLAN_CURRENCY_OPTIONS, PUSH_SERVICE_WORKER_SCRIPT, PricingPage, PushNotificationProvider, 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, resolveMaxUsers, useAllQuotaUsage, useBillingPortal, useCancelSubscription, useCreateCheckoutSession, useInvoice, useInvoices, usePlanGroup, usePlanGroupVersions, usePublicPlanGroupVersion, usePublicPlans, usePushNotifications, useQuotaUsageContext, useQuotaUsageStatus, useRecordUsage, useResumeSubscription, useSaaSAuth, useSaaSOs, useSaaSSettings, useSaaSWorkspaces, useSeatStatus, useSubscription, useSubscriptionContext, useSubscriptionManagement, useTrialStatus, useUpdateSubscription, useUsageLogs, useUserAttributes, useUserFeatures, validateInvite };
+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, InviteBlockReason, InviteValidation, InvoiceStatus, MaxUsersConfig, OnWorkspaceChangeParams, PlanVersionWithPricingVariants, PricingPageDetails, PricingPageProps, QuotaDisplayValue, QuotaDisplayWithOverage, QuotaUsageContextValue, SeatStatus, SubscriptionContextValue, TrialStatus, UserCreatedEventData, UserUpdatedEventData, WorkspaceChangedEventData, WorkspaceCreatedEventData, WorkspaceDeletedEventData, WorkspaceUpdatedEventData, WorkspaceUserAddedEventData, WorkspaceUserRemovedEventData, WorkspaceUserRoleChangedEventData };