@buildbase/sdk 0.0.13 → 0.0.15

package/README.md

@@ -12,6 +12,7 @@ A React SDK for [BuildBase](https://www.buildbase.app/) that provides essential
 - [Feature Flags](#️-feature-flags)
 - [User Management](#-user-management)
 - [Workspace Management](#-complete-workspace-management)
+- [Public Pricing (No Login)](#-public-pricing-no-login)
 - [Beta Form Component](#-beta-form-component)
 - [Event System](#-event-system)
 - [Error Handling](#️-error-handling)
@@ -406,6 +407,71 @@ function WorkspaceManager() {
 }
 ```
 
+## 💰 Public Pricing (No Login)
+
+Display subscription plans and pricing on public pages (e.g. marketing site, pricing page) without requiring users to log in.
+
+### usePublicPlans
+
+Fetches public plans by slug. Returns `items` (features, limits, quotas) and `plans` (with pricing). You construct the layout from this data:
+
+```tsx
+import { usePublicPlans } from '@buildbase/sdk';
+
+function PublicPricingPage() {
+  const { items, plans, loading, error } = usePublicPlans('main-pricing');
+
+  if (loading) return <Loading />;
+  if (error) return <Error message={error} />;
+
+  return (
+    <div>
+      {plans.map(plan => (
+        <PlanCard key={plan._id} plan={plan} items={items} />
+      ))}
+    </div>
+  );
+}
+```
+
+### PricingPage Component
+
+Use the `PricingPage` component with a render-prop pattern:
+
+```tsx
+import { PricingPage } from '@buildbase/sdk';
+
+function PublicPricingPage() {
+  return (
+    <PricingPage slug="main-pricing">
+      {({ loading, error, items, plans, refetch }) => {
+        if (loading) return <Loading />;
+        if (error) return <Error message={error} />;
+
+        return (
+          <div>
+            {plans.map(plan => (
+              <PlanCard key={plan._id} plan={plan} items={items} />
+            ))}
+          </div>
+        );
+      }}
+    </PricingPage>
+  );
+}
+```
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `slug` | `string` | Plan group slug (e.g. 'main-pricing', 'enterprise') |
+| `children` | `(details) => ReactNode` | Render prop receiving `{ loading, error, items, plans, refetch }` |
+| `loadingFallback` | `ReactNode` | Custom loading UI (defaults to skeleton) |
+| `errorFallback` | `(error: string) => ReactNode` | Custom error UI |
+
+**Response shape**: `items` = subscription item definitions (features, limits, quotas with category); `plans` = plan versions with `pricing`, `quotas`, `features`, `limits`.
+
+**Backend requirement**: `GET /api/v1/public/{orgId}/plans/{groupSlug}` must be implemented and allow unauthenticated access.
+
 ## 📝 Beta Form Component
 
 Use the pre-built `BetaForm` component for signup/waitlist forms:

package/dist/index.d.ts

@@ -27,6 +27,12 @@ interface ISubscription {
     cancelAtPeriodEnd: boolean;
     createdAt: string;
     updatedAt: string;
+    plan?: {
+        _id: string;
+        name: string;
+        slug: string;
+        description?: string;
+    };
 }
 interface ISubscriptionItem {
     _id: string;
@@ -205,10 +211,47 @@ interface ISubscriptionUpdateResponse {
     createdAt: string;
     updatedAt: string;
 }
+interface IPublicPlanItemCategory {
+    name: string;
+    slug: string;
+}
+interface IPublicPlanItem {
+    _id: string;
+    name: string;
+    slug: 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;
+}
+interface IPublicPlanVersion {
+    _id: string;
+    name: string;
+    version: number;
+    status: 'draft' | 'published';
+    pricing: IPublicPlanPricing;
+    quotas: Record<string, IPublicPlanQuotaValue>;
+    features: Record<string, boolean>;
+    limits: Record<string, number>;
+}
+interface IPublicPlansResponse {
+    items: IPublicPlanItem[];
+    plans: IPublicPlanVersion[];
+}
 type InvoiceStatus = 'draft' | 'open' | 'paid' | 'uncollectible' | 'void';
 interface IInvoice {
     id: string;
     amount_due: number;
+    number: string | null;
     amount_paid: number;
     currency: string;
     status: InvoiceStatus;
@@ -238,6 +281,7 @@ interface IWorkspace {
     roles: string[];
     createdBy: string | IUser;
     features: Record<string, boolean>;
+    subscription?: ISubscription | null;
 }
 interface IWorkspaceFeature {
     _id: string;
@@ -422,6 +466,52 @@ interface BetaFormProps {
 }
 declare const BetaForm: react__default.FC<BetaFormProps>;
 
+interface PricingPageDetails {
+    /** Whether plan data is being fetched */
+    loading: boolean;
+    /** Error message if fetch failed */
+    error: string | null;
+    /** Subscription items (features, limits, quotas) */
+    items: IPublicPlanItem[];
+    /** Plan versions with pricing, features, limits, quotas */
+    plans: IPublicPlanVersion[];
+    /** Refetch plan data */
+    refetch: () => Promise<void>;
+}
+interface PricingPageProps {
+    /** Plan group slug (e.g. 'main-pricing', 'enterprise') */
+    slug: string;
+    /** Render prop receiving plan details - construct layout from items and plans */
+    children: (details: PricingPageDetails) => ReactNode;
+    /** Custom loading UI. Defaults to skeleton. */
+    loadingFallback?: ReactNode;
+    /** Custom error UI. Receives error message. */
+    errorFallback?: (error: string) => ReactNode;
+}
+/**
+ * Fetches and provides plan/pricing details for public pricing pages (no login required).
+ * Returns items (features, limits, quotas) and plans (with pricing) - user constructs layout.
+ *
+ * @example
+ * ```tsx
+ * <PricingPage slug="main-pricing">
+ *   {({ loading, error, items, plans, refetch }) => {
+ *     if (loading) return <Loading />;
+ *     if (error) return <Error message={error} />;
+ *
+ *     return (
+ *       <div>
+ *         {plans.map(plan => (
+ *           <PlanCard key={plan._id} plan={plan} items={items} />
+ *         ))}
+ *       </div>
+ *     );
+ *   }}
+ * </PricingPage>
+ * ```
+ */
+declare function PricingPage({ slug, children, loadingFallback, errorFallback, }: PricingPageProps): react_jsx_runtime.JSX.Element;
+
 interface IProps$2 {
     children: React.ReactNode;
 }
@@ -688,6 +778,8 @@ declare const WhenUserFeatureEnabled: (props: IProps) => react.ReactNode;
  */
 declare const WhenUserFeatureDisabled: (props: IProps) => react.ReactNode;
 
+type WorkspaceSettingsSection = 'profile' | 'general' | 'users' | 'subscription' | 'features' | 'danger';
+
 /**
  * Main authentication hook for the SDK.
  * Provides authentication state, user session, and auth actions.
@@ -752,7 +844,7 @@ declare const WhenUserFeatureDisabled: (props: IProps) => react.ReactNode;
 declare function useSaaSAuth(): {
     signIn: () => Promise<void>;
     signOut: () => Promise<void>;
-    openWorkspaceSettings: (section?: "profile" | "general" | "users" | "features" | "danger") => void;
+    openWorkspaceSettings: (section?: WorkspaceSettingsSection) => void;
     isAuthenticated: boolean;
     isLoading: boolean;
     isRedirecting: boolean;
@@ -1050,6 +1142,59 @@ declare function WorkspaceSwitcher(props: {
     trigger: (isLoading: boolean, currentWorkspace: IWorkspace | null) => ReactNode;
 }): react_jsx_runtime.JSX.Element;
 
+/**
+ * Hook to get public plans by slug (no auth required).
+ * Returns items (features, limits, quotas) and plans (with pricing).
+ * Uses orgId from SaaSOSProvider - must be inside provider.
+ *
+ * @param slug - Plan group slug (e.g. 'main-pricing', 'enterprise')
+ * @returns { items, plans, loading, error, refetch }
+ */
+declare const usePublicPlans: (slug: string) => {
+    items: IPublicPlanItem[];
+    plans: IPublicPlanVersion[];
+    loading: boolean;
+    error: string | null;
+    refetch: () => Promise<void>;
+};
+/**
+ * Hook to get a single plan group version by ID (no auth required).
+ * 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. Pass null/undefined to disable fetching.
+ * @returns An object containing:
+ * - `planGroupVersion`: Plan group version data (null if not loaded)
+ * - `loading`: Boolean indicating if data is being fetched
+ * - `error`: Error message string (null if no error)
+ * - `refetch()`: Function to manually refetch
+ *
+ * @example
+ * ```tsx
+ * function PublicPricingPage() {
+ *   const groupVersionId = 'your-plan-group-version-id'; // from config or URL
+ *   const { planGroupVersion, loading } = usePublicPlanGroupVersion(groupVersionId);
+ *
+ *   if (loading) return <Loading />;
+ *   if (!planGroupVersion) return null;
+ *
+ *   const plans = Array.isArray(planGroupVersion.planVersionIds)
+ *     ? planGroupVersion.planVersionIds.filter((p): p is IPlanVersionWithPlan => typeof p !== 'string')
+ *     : [];
+ *
+ *   return (
+ *     <div>
+ *       {plans.map(plan => <PlanCard key={plan._id} plan={plan} />)}
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+declare const usePublicPlanGroupVersion: (groupVersionId: string | null | undefined) => {
+    planGroupVersion: IPlanGroupVersion | null;
+    loading: boolean;
+    error: string | null;
+    refetch: () => Promise<void>;
+};
 /**
  * Hook to get and manage the current subscription for a workspace.
  * Automatically fetches subscription when workspaceId changes.
@@ -1558,5 +1703,5 @@ declare class EventEmitter {
 }
 declare const eventEmitter: EventEmitter;
 
-export { ApiVersion, AuthStatus, BetaForm, SaaSOSProvider, WhenAuthenticated, WhenRoles, WhenUnauthenticated, WhenUserFeatureDisabled, WhenUserFeatureEnabled, WhenWorkspaceFeatureDisabled, WhenWorkspaceFeatureEnabled, WhenWorkspaceRoles, WorkspaceSwitcher, eventEmitter, useCreateCheckoutSession, useInvoice, useInvoices, usePlanGroup, usePlanGroupVersions, 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, IQuotaValue, ISubscription, ISubscriptionItem, ISubscriptionResponse, ISubscriptionUpdateRequest, ISubscriptionUpdateResponse, InvoiceStatus, OnWorkspaceChangeParams, UserCreatedEventData, UserUpdatedEventData, WorkspaceChangedEventData, WorkspaceCreatedEventData, WorkspaceDeletedEventData, WorkspaceUpdatedEventData, WorkspaceUserAddedEventData, WorkspaceUserRemovedEventData, WorkspaceUserRoleChangedEventData };
+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 };