@buildbase/sdk 0.0.24 → 0.0.26

package/README.md

@@ -11,6 +11,7 @@ A React SDK for [BuildBase](https://www.buildbase.app/) that provides essential
 - [Role-Based Access Control](#-role-based-access-control)
 - [Feature Flags](#️-feature-flags)
 - [Subscription Gates](#-subscription-gates)
+- [Trial Gates](#-trial-gates)
 - [User Management](#-user-management)
 - [Workspace Management](#-complete-workspace-management)
 - [Public Pricing (No Login)](#-public-pricing-no-login)
@@ -35,6 +36,9 @@ A React SDK for [BuildBase](https://www.buildbase.app/) that provides essential
 - **👥 Role-Based Access Control** - User roles and workspace-specific permissions
 - **🎯 Feature Flags** - Workspace-level and user-level feature toggles
 - **📋 Subscription Gates** - Show or hide UI based on current workspace subscription (plan)
+- **⏳ Trial Gates** - `WhenTrialing`, `WhenNotTrialing`, `WhenTrialEnding` components + `useTrialStatus` hook
+- **💺 Seat-Based Pricing** - Per-seat billing with included seats, billable seat tracking, and seat limit enforcement
+- **💱 Multi-Currency** - Per-currency pricing variants with workspace billing currency lock
 - **📊 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
@@ -442,6 +446,74 @@ function SubscriptionStatus() {
 - When subscription is updated via SDK (e.g. `useUpdateSubscription`, cancel, resume) — refetch is triggered automatically.
 - When you call `refetch()` (e.g. after redirect from checkout).
 
+## ⏳ Trial Gates
+
+Control UI based on trial state. Works with Stripe-native trials (both card-required and no-card).
+
+### Trial Gate Components
+
+```tsx
+import { WhenTrialing, WhenNotTrialing, WhenTrialEnding } from '@buildbase/sdk';
+
+function TrialExample() {
+  return (
+    <div>
+      {/* Show only during active trial */}
+      <WhenTrialing>
+        <TrialBanner />
+      </WhenTrialing>
+
+      {/* Show when NOT trialing (active, canceled, or no subscription) */}
+      <WhenNotTrialing>
+        <RegularContent />
+      </WhenNotTrialing>
+
+      {/* Show when trial ends within N days (default: 3) */}
+      <WhenTrialEnding daysThreshold={7}>
+        <UpgradeUrgentBanner />
+      </WhenTrialEnding>
+    </div>
+  );
+}
+```
+
+| Component         | Renders when                                             |
+| ----------------- | -------------------------------------------------------- |
+| `WhenTrialing`    | Subscription status is `trialing`                        |
+| `WhenNotTrialing` | Subscription status is NOT `trialing`                    |
+| `WhenTrialEnding` | Trialing AND trial ends within `daysThreshold` days (default 3) |
+
+All trial gates support `loadingComponent` and `fallbackComponent` props.
+
+### useTrialStatus
+
+Hook that computes trial information from the subscription context:
+
+```tsx
+import { useTrialStatus } from '@buildbase/sdk';
+
+function TrialInfo() {
+  const { isTrialing, daysRemaining, trialEndsAt, isTrialEnding } = useTrialStatus();
+
+  if (!isTrialing) return null;
+
+  return (
+    <div>
+      <p>Trial ends in {daysRemaining} days</p>
+      {isTrialEnding && <p>Upgrade now to keep access!</p>}
+    </div>
+  );
+}
+```
+
+| Property        | Type           | Description                                      |
+| --------------- | -------------- | ------------------------------------------------ |
+| `isTrialing`    | `boolean`      | Whether subscription is in trial                 |
+| `daysRemaining` | `number`       | Days left in trial (0 if not trialing or expired) |
+| `trialEndsAt`   | `Date \| null` | Trial end date                                   |
+| `trialStartedAt`| `Date \| null` | Trial start date                                 |
+| `isTrialEnding` | `boolean`      | True when 3 or fewer days remaining              |
+
 ## 👤 User Management
 
 ### User Attributes
@@ -1168,6 +1240,15 @@ All SDK API clients extend a shared base class and are exported from the package
 | `WorkspaceApi`   | Workspaces, subscription, invoices, quota usage, users                            |
 | `SettingsApi`    | Organization settings                                                           |
 
+### Components
+
+| Component | Purpose |
+| --- | --- |
+| `SubscriptionContextProvider` | Provides subscription data to children (included in SaaSOSProvider) |
+| `WhenSubscription`, `WhenNoSubscription`, `WhenSubscriptionToPlans` | Subscription gate components |
+| `WhenTrialing`, `WhenNotTrialing`, `WhenTrialEnding` | Trial gate components |
+| `WhenQuotaAvailable`, `WhenQuotaExhausted`, `WhenQuotaOverage` | Quota gate components |
+
 ### Currency, pricing variant & quota utilities
 
 | Category | Exports |
@@ -1203,6 +1284,7 @@ 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 |
+| `useTrialStatus()`         | Trial state: `isTrialing`, `daysRemaining`, `trialEndsAt`, `isTrialEnding`                              |
 | 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`                             |

package/dist/index.d.ts

@@ -1716,6 +1716,13 @@ declare class WorkspaceApi extends BaseApi {
      * Returns checkout session if payment is required, otherwise returns subscription update response
      */
     updateSubscription(workspaceId: string, request: ISubscriptionUpdateRequest): Promise<ISubscriptionUpdateResponse | ICheckoutSessionResponse>;
+    /**
+     * Create a Stripe Customer Portal session for managing payment methods, invoices, etc.
+     * Returns the portal URL — redirect user to it.
+     */
+    createBillingPortalSession(workspaceId: string, returnUrl?: string): Promise<{
+        url: string;
+    }>;
     /**
      * List invoices for a workspace subscription
      * @param workspaceId - The workspace ID
@@ -2268,6 +2275,24 @@ declare const useInvoices: (workspaceId: string | null | undefined, limit?: numb
     error: string | null;
     refetch: () => Promise<void>;
 };
+/**
+ * Hook to open the Stripe Customer Portal for managing payment methods, invoices, and subscription.
+ *
+ * @example
+ * ```tsx
+ * const { openBillingPortal, loading } = useBillingPortal(workspaceId);
+ * <Button onClick={() => openBillingPortal()} disabled={loading}>
+ *   Manage Payment Method
+ * </Button>
+ * ```
+ */
+declare const useBillingPortal: (workspaceId: string | null | undefined) => {
+    openBillingPortal: (returnUrl?: string) => Promise<{
+        url: string;
+    }>;
+    loading: boolean;
+    error: string | null;
+};
 /**
  * Hook to get a single invoice by ID.
  * Automatically fetches when workspaceId or invoiceId changes.
@@ -2862,5 +2887,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, 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 { 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, useBillingPortal, 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 };