@buildbase/sdk 0.0.26 → 0.0.27

package/README.md

@@ -12,6 +12,7 @@ A React SDK for [BuildBase](https://www.buildbase.app/) that provides essential
 - [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)
@@ -37,6 +38,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)
 - **⏳ 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
@@ -514,6 +516,40 @@ function TrialInfo() {
 | `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
@@ -1285,6 +1321,7 @@ Prefer these SDK hooks for state and operations instead of `useAppSelector`:
 | `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>;
@@ -2662,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
@@ -2887,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, 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 { 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 };