@buildbase/sdk 0.0.25 → 0.0.27

package/README.md

@@ -11,6 +11,8 @@ 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)
+- [Push Notifications](#-push-notifications)
 - [User Management](#-user-management)
 - [Workspace Management](#-complete-workspace-management)
 - [Public Pricing (No Login)](#-public-pricing-no-login)
@@ -35,6 +37,10 @@ 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
+- **🔔 Push Notifications** - Browser push notifications with `usePushNotifications` hook, auto-triggers for billing events, and campaign management
+- **💺 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 +448,108 @@ 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              |
+
+## 🔔 Push Notifications
+
+Browser push notifications — built into the SDK. Users can enable/disable from the **Notifications** tab in workspace settings. Billing events (payment failed, trial ending) auto-send push notifications.
+
+**Only setup required:** Create `public/push-sw.js` in your app:
+
+```js
+self.addEventListener('push', function(event) {
+  if (!event.data) return;
+  try {
+    var payload = event.data.json();
+    event.waitUntil(self.registration.showNotification(payload.title || 'Notification', {
+      body: payload.body || '',
+      icon: payload.icon || undefined,
+      badge: payload.icon || undefined,
+      data: { url: payload.url, ...(payload.data || {}) },
+    }));
+  } catch (e) { console.error('[PushSW]', e); }
+});
+
+self.addEventListener('notificationclick', function(event) {
+  event.notification.close();
+  var url = event.notification.data && event.notification.data.url;
+  if (url) {
+    event.waitUntil(clients.matchAll({ type: 'window', includeUncontrolled: true }).then(function(list) {
+      for (var i = 0; i < list.length; i++) { if (list[i].url === url && 'focus' in list[i]) return list[i].focus(); }
+      if (clients.openWindow) return clients.openWindow(url);
+    }));
+  }
+});
+```
+
+Everything else is built-in — permission handling, subscribe/unsubscribe, settings UI, billing auto-triggers, and browser-specific unblock instructions.
+
 ## 👤 User Management
 
 ### User Attributes
@@ -1168,6 +1276,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 +1320,8 @@ 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`                              |
+| `usePushNotifications()`   | Push notification state and actions: `isSubscribed`, `subscribe()`, `unsubscribe()`                     |
 | 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

@@ -1406,7 +1406,7 @@ declare function useQuotaUsageContext(): QuotaUsageContextValue;
  */
 declare function invalidateQuotaUsage(): void;
 
-type WorkspaceSettingsSection = 'profile' | 'general' | 'users' | 'subscription' | 'usage' | 'features' | 'danger';
+type WorkspaceSettingsSection = 'profile' | 'general' | 'users' | 'subscription' | 'usage' | 'features' | 'notifications' | 'danger';
 
 declare function useSaaSAuth(): {
     signIn: () => Promise<void>;
@@ -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.
@@ -2637,6 +2662,56 @@ declare function useSeatStatus(workspace: {
     billingCurrency?: string | null;
 } | null): SeatStatus;
 
+interface PushNotificationState {
+    /** Browser's Notification.permission: 'default' | 'granted' | 'denied' */
+    permission: NotificationPermission;
+    /** Whether this device is subscribed to push notifications */
+    isSubscribed: boolean;
+    /** Whether the browser supports push notifications */
+    isSupported: boolean;
+    /** Loading state for subscribe/unsubscribe operations */
+    loading: boolean;
+    /** Error message from the last operation */
+    error: string | null;
+}
+interface PushNotificationContextValue extends PushNotificationState {
+    /** Request notification permission from the browser. Returns true if granted. */
+    requestPermission: () => Promise<boolean>;
+    /** Subscribe this device to push notifications (requests permission if needed). */
+    subscribe: () => Promise<void>;
+    /** Unsubscribe this device from push notifications. */
+    unsubscribe: () => Promise<void>;
+}
+interface PushNotificationProviderProps {
+    children: react__default.ReactNode;
+    /** Path to the service worker file (default: '/push-sw.js') */
+    serviceWorkerPath?: string;
+    /** Automatically subscribe after permission is granted on login (default: false) */
+    autoSubscribe?: boolean;
+}
+declare const PushNotificationProvider: react__default.FC<PushNotificationProviderProps>;
+/**
+ * Hook to access push notification state and actions.
+ * Must be used within PushNotificationProvider (included in SaaSOSProvider when push config is provided).
+ */
+declare function usePushNotifications(): PushNotificationContextValue;
+
+/**
+ * Push notification service worker source code.
+ * Export this string and write it to a file in your app's `public/` directory.
+ *
+ * @example
+ * ```ts
+ * // scripts/generate-sw.ts
+ * import { PUSH_SERVICE_WORKER_SCRIPT } from '@buildbase/sdk';
+ * import fs from 'fs';
+ * fs.writeFileSync('public/push-sw.js', PUSH_SERVICE_WORKER_SCRIPT);
+ * ```
+ *
+ * Or manually create `public/push-sw.js` with this content.
+ */
+declare const PUSH_SERVICE_WORKER_SCRIPT = "\n// BuildBase Push Notification Service Worker\n// Place this file in your app's public directory (e.g. public/push-sw.js)\n\nself.addEventListener('push', function(event) {\n  if (!event.data) return;\n\n  try {\n    var payload = event.data.json();\n    var title = payload.title || 'Notification';\n    var options = {\n      body: payload.body || '',\n      icon: payload.icon || undefined,\n      badge: payload.icon || undefined,\n      data: { url: payload.url, ...(payload.data || {}) },\n      tag: 'buildbase-push-' + Date.now(),\n    };\n\n    event.waitUntil(\n      self.registration.showNotification(title, options)\n    );\n  } catch (e) {\n    console.error('[PushSW] Failed to show notification:', e);\n  }\n});\n\nself.addEventListener('notificationclick', function(event) {\n  event.notification.close();\n\n  var url = event.notification.data && event.notification.data.url;\n  if (url) {\n    event.waitUntil(\n      clients.matchAll({ type: 'window', includeUncontrolled: true }).then(function(clientList) {\n        for (var i = 0; i < clientList.length; i++) {\n          var client = clientList[i];\n          if (client.url === url && 'focus' in client) {\n            return client.focus();\n          }\n        }\n        if (clients.openWindow) {\n          return clients.openWindow(url);\n        }\n      })\n    );\n  }\n});\n";
+
 /**
  * EventEmitter class to handle and trigger event callbacks
  * This class manages all event listeners and provides methods to trigger events
@@ -2862,5 +2937,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, 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 };