@buildbase/sdk 0.0.42 → 0.0.44

package/README.md

@@ -47,7 +47,7 @@ Also works server-side (Next.js API routes, Express, Hono) — see [Server-Side
 - **📬 Notifications** - Email + push notification system with per-event channel control, workspace preferences, and server-side `notification.send()` API
 - **💺 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
-- **🤝 Affiliate Tracking** - Pass referral data to Stripe checkout via `stripeOptions` (Rewardful, Endorsely, FirstPromoter, etc.)
+- **🤝 Affiliate Tracking** - Pass referral data to Stripe checkout via `getCheckoutStripeParams` prop (Rewardful, Endorsely, FirstPromoter, etc.)
 - **📊 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
@@ -306,24 +306,35 @@ import { saveAuthIntent, consumeAuthIntent, clearAuthIntent } from '@buildbase/s
 
 ### Affiliate / Referral Tracking
 
-Pass affiliate data to Stripe checkout sessions via `stripeOptions` on the checkout request:
+Pass affiliate/referral data to Stripe checkout sessions via the `getCheckoutStripeParams` prop on `SaaSOSProvider`. This async callback is called before every checkout session is created, so you can fetch referral IDs, read cookies, or call any async API:
 
 ```tsx
-createCheckoutSession({
-  planVersionId: '...',
-  stripeOptions: {
+<SaaSOSProvider
+  serverUrl="https://your-api-server.com"
+  version={ApiVersion.V1}
+  orgId="your-org-id"
+  auth={authConfig}
+  getCheckoutStripeParams={async (request) => {
     // Rewardful, FirstPromoter, PartnerStack — read client_reference_id
-    clientReferenceId: Rewardful.referral,
+    const referralId = await getRewardfulReferralId();
 
-    // Endorsely — reads subscription metadata
-    subscriptionMetadata: { endorsely_referral: window.endorsely_referral },
+    return {
+      clientReferenceId: referralId,
 
-    // Custom tracking on the checkout session
-    metadata: { campaign: 'summer-sale' },
-  },
-});
+      // Endorsely — reads subscription metadata
+      subscriptionMetadata: { endorsely_referral: window.endorsely_referral },
+
+      // Custom tracking on the checkout session
+      metadata: { campaign: 'summer-sale' },
+    };
+  }}
+>
+  <App />
+</SaaSOSProvider>
 ```
 
+The returned object is merged into the Stripe checkout session. You can return any combination of the fields below, or `undefined` to proceed without extra options:
+
 | Field                  | Stripe mapping                | Use case                               |
 | ---------------------- | ----------------------------- | -------------------------------------- |
 | `clientReferenceId`    | `client_reference_id`         | Rewardful, FirstPromoter, etc.         |
@@ -1845,13 +1856,16 @@ All TypeScript types are exported for type safety. See the [TypeScript definitio
 
 ### SaaSOSProvider Props
 
-| Prop        | Type          | Required | Description                                                          |
-| ----------- | ------------- | -------- | -------------------------------------------------------------------- |
-| `serverUrl` | `string`      | ✅       | API server URL (must be valid URL)                                   |
-| `version`   | `ApiVersion`  | ✅       | API version (currently only `'v1'`)                                  |
-| `orgId`     | `string`      | ✅       | Organization ID (must be valid MongoDB ObjectId - 24 hex characters) |
-| `auth`      | `IAuthConfig` | ❌       | Authentication configuration                                         |
-| `children`  | `ReactNode`   | ✅       | React children                                                       |
+| Prop                       | Type                        | Required | Description                                                                                      |
+| -------------------------- | --------------------------- | -------- | ------------------------------------------------------------------------------------------------ |
+| `serverUrl`                | `string`                    | ✅       | API server URL (must be valid URL)                                                               |
+| `version`                  | `ApiVersion`                | ✅       | API version (currently only `'v1'`)                                                              |
+| `orgId`                    | `string`                    | ✅       | Organization ID (must be valid MongoDB ObjectId - 24 hex characters)                             |
+| `auth`                     | `IAuthConfig`               | ❌       | Authentication configuration                                                                     |
+| `locale`                   | `SDKLocale`                 | ❌       | SDK UI language (`'en'`, `'es'`, `'fr'`, `'de'`, `'ja'`, `'zh'`, `'hi'`, `'ar'`)                |
+| `defaultPermissions`       | `Record<string, string[]>`  | ❌       | Default app permissions per role                                                                 |
+| `getCheckoutStripeParams`  | `GetCheckoutStripeParams`   | ❌       | Async callback called before every Stripe checkout to return metadata, referral IDs, etc.        |
+| `children`                 | `ReactNode`                 | ✅       | React children                                                                                   |
 
 ### Auth Configuration
 

package/dist/index.d.ts

@@ -360,6 +360,17 @@ interface ICheckoutStripeOptions {
     /** Custom metadata merged into `subscription_data.metadata` on the Stripe session. */
     subscriptionMetadata?: Record<string, string>;
 }
+/**
+ * Async callback called before every checkout session is created.
+ * Use it to return Stripe-level options (metadata, affiliate IDs, etc.)
+ * that should be forwarded to the Stripe checkout session.
+ *
+ * Return an `ICheckoutStripeOptions` object to merge into the request,
+ * or `undefined`/`void` to proceed without extra options.
+ *
+ * @param request - The checkout request about to be sent (read-only).
+ */
+type GetCheckoutStripeParams = (request: Readonly<ICheckoutSessionRequest>) => Promise<ICheckoutStripeOptions | void> | ICheckoutStripeOptions | void;
 /** Request body for POST .../workspaces/:id/subscription/checkout. */
 interface ICheckoutSessionRequest {
     planVersionId: string;
@@ -2220,4 +2231,4 @@ interface BuildBaseResult extends ScopedActions {
 declare function BuildBase(config: BuildBaseConfig): BuildBaseResult;
 
 export { ApiVersion, AuthApi, AuthStatus, BB_PARAM, BaseApi, BetaForm, BillingIntervals, BuildBase, CURRENCY_DISPLAY, CURRENCY_FLAG, DEFAULT_ROLE_PERMISSIONS, DunningState, EventEmitter, InvoiceStatuses, PLAN_CURRENCY_CODES, PLAN_CURRENCY_OPTIONS, PUSH_SERVICE_WORKER_SCRIPT, Permission, PushApi, SDKEvent, SettingsApi, SubscriptionItemType, SubscriptionStatus, UserApi, WorkspaceApi, calculateBillableSeats, calculateSeatOverageCents, calculateTotalSubscriptionCents, cleanBBParams, clearAuthIntent, consumeAuthIntent, createBBUrl, createCheckoutRedirectUrls, BuildBase as default, eventEmitter, formatCents, formatOverageRate, formatOverageRateWithLabel, formatQuotaIncludedOverage, formatQuotaWithPrice, getAvailableCurrenciesFromPlans, getBasePriceCents, getBillingIntervalAndCurrencyFromPriceId, getCurrencyFlag, getCurrencySymbol, getDisplayCurrency, getPerSeatPriceCents, getPricingVariant, getQuotaDisplayValue, getQuotaDisplayWithVariant, getQuotaOverageCents, getQuotaUnitLabelFromName, getSeatPricing, getStripePriceIdForInterval, hasPermission, invalidateQuotaUsage, invalidateSubscription, parseWebhookEvent, readBBParams, resolveMaxUsers, resolvePermissions, safeRedirect, saveAuthIntent, validateInvite, validateRedirectUrl, verifyWebhookSignature };
-export type { BetaFormData, BetaFormResponse, BillingInterval, BuildBaseConfig, BuildBaseResult, BuildBaseSession, CheckoutResult, EventData, EventType, FeatureActions, FormatQuotaWithPriceOptions, IAllQuotaUsageResponse, IBaseApiConfig, IBasePricing, IBetaConfig, ICheckoutSessionRequest, ICheckoutSessionResponse, ICheckoutStripeOptions, IEventCallbacks, IInvoice, IInvoiceListResponse, IInvoiceResponse, IOsConfig, IOsState, 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, InvoiceActions, InvoiceStatus, MaxUsersConfig, NotificationData, NotificationEvent, NotificationResult, OnWorkspaceChangeParams, PermissionActions, PermissionContext, PermissionKey, PlanActions, PlanVersionWithPricingVariants, QuotaDisplayValue, QuotaDisplayWithOverage, RolePermissionMap, ScopedActions, SettingsActions, SubscriptionActions, SubscriptionStatusType, UsageActions, UserActions, UserCreatedEventData, UserUpdatedEventData, WorkspaceActions, WorkspaceChangedEventData, WorkspaceCreatedEventData, WorkspaceDeletedEventData, WorkspaceUpdatedEventData, WorkspaceUserAddedEventData, WorkspaceUserRemovedEventData, WorkspaceUserRoleChangedEventData };
+export type { BetaFormData, BetaFormResponse, BillingInterval, BuildBaseConfig, BuildBaseResult, BuildBaseSession, CheckoutResult, EventData, EventType, FeatureActions, FormatQuotaWithPriceOptions, GetCheckoutStripeParams, IAllQuotaUsageResponse, IBaseApiConfig, IBasePricing, IBetaConfig, ICheckoutSessionRequest, ICheckoutSessionResponse, ICheckoutStripeOptions, IEventCallbacks, IInvoice, IInvoiceListResponse, IInvoiceResponse, IOsConfig, IOsState, 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, InvoiceActions, InvoiceStatus, MaxUsersConfig, NotificationData, NotificationEvent, NotificationResult, OnWorkspaceChangeParams, PermissionActions, PermissionContext, PermissionKey, PlanActions, PlanVersionWithPricingVariants, QuotaDisplayValue, QuotaDisplayWithOverage, RolePermissionMap, ScopedActions, SettingsActions, SubscriptionActions, SubscriptionStatusType, UsageActions, UserActions, UserCreatedEventData, UserUpdatedEventData, WorkspaceActions, WorkspaceChangedEventData, WorkspaceCreatedEventData, WorkspaceDeletedEventData, WorkspaceUpdatedEventData, WorkspaceUserAddedEventData, WorkspaceUserRemovedEventData, WorkspaceUserRoleChangedEventData };

package/dist/react/index.d.ts

@@ -364,6 +364,17 @@ interface ICheckoutStripeOptions {
     /** Custom metadata merged into `subscription_data.metadata` on the Stripe session. */
     subscriptionMetadata?: Record<string, string>;
 }
+/**
+ * Async callback called before every checkout session is created.
+ * Use it to return Stripe-level options (metadata, affiliate IDs, etc.)
+ * that should be forwarded to the Stripe checkout session.
+ *
+ * Return an `ICheckoutStripeOptions` object to merge into the request,
+ * or `undefined`/`void` to proceed without extra options.
+ *
+ * @param request - The checkout request about to be sent (read-only).
+ */
+type GetCheckoutStripeParams = (request: Readonly<ICheckoutSessionRequest>) => Promise<ICheckoutStripeOptions | void> | ICheckoutStripeOptions | void;
 /** Request body for POST .../workspaces/:id/subscription/checkout. */
 interface ICheckoutSessionRequest {
     planVersionId: string;
@@ -2453,6 +2464,23 @@ interface SaaSOSProviderProps extends IOsState {
      * ```
      */
     defaultPermissions?: Record<string, string[]>;
+    /**
+     * Async callback called before every Stripe checkout session is created.
+     * Use it to return Stripe-level params (metadata, client reference ID, subscription metadata)
+     * that will be forwarded to the Stripe checkout session.
+     *
+     * @example
+     * ```tsx
+     * <SaaSOSProvider
+     *   getCheckoutStripeParams={async (request) => ({
+     *     clientReferenceId: await getRewardfulReferralId(),
+     *     metadata: { campaign: 'spring-sale' },
+     *     subscriptionMetadata: { affiliateId: 'aff-123' },
+     *   })}
+     * >
+     * ```
+     */
+    getCheckoutStripeParams?: GetCheckoutStripeParams;
 }
 declare const SaaSOSProvider: react__default.FC<SaaSOSProviderProps>;
 
@@ -4341,4 +4369,4 @@ declare const PushNotificationProvider: react__default.FC<PushNotificationProvid
 declare function usePushNotifications(): PushNotificationContextValue;
 
 export { ApiVersion, AuthApi, AuthStatus, BB_PARAM, BaseApi, BetaForm, BillingIntervals, CURRENCY_DISPLAY, CURRENCY_FLAG, DEFAULT_ROLE_PERMISSIONS, DunningState, EventEmitter, InvoiceStatuses, PLAN_CURRENCY_CODES, PLAN_CURRENCY_OPTIONS, PUSH_SERVICE_WORKER_SCRIPT, Permission, PricingPage, PushApi, PushNotificationProvider, QuotaUsageContextProvider, SDKEvent, SETTINGS_SCREENS, SUPPORTED_LOCALES, SaaSOSProvider, SettingsApi, SettingsScreen, SubscriptionContextProvider, SubscriptionItemType, SubscriptionStatus, UserApi, WhenAuthenticated, WhenNoSubscription, WhenNotTrialing, WhenPermission, WhenQuotaAvailable, WhenQuotaExhausted, WhenQuotaOverage, WhenQuotaThreshold, WhenRoles, WhenSubscription, WhenSubscriptionToPlans, WhenTrialEnding, WhenTrialing, WhenUnauthenticated, WhenUserFeatureDisabled, WhenUserFeatureEnabled, WhenWorkspaceFeatureDisabled, WhenWorkspaceFeatureEnabled, WhenWorkspaceRoles, WorkspaceApi, WorkspaceSwitcher, calculateBillableSeats, calculateSeatOverageCents, calculateTotalSubscriptionCents, cleanBBParams, clearAuthIntent, consumeAuthIntent, createBBUrl, createCheckoutRedirectUrls, eventEmitter, formatCents, formatOverageRate, formatOverageRateWithLabel, formatQuotaIncludedOverage, formatQuotaWithPrice, getAvailableCurrenciesFromPlans, getBasePriceCents, getBillingIntervalAndCurrencyFromPriceId, getCurrencyFlag, getCurrencySymbol, getDisplayCurrency, getPerSeatPriceCents, getPricingVariant, getQuotaDisplayValue, getQuotaDisplayWithVariant, getQuotaOverageCents, getQuotaUnitLabelFromName, getSeatPricing, getStripePriceIdForInterval, hasPermission, invalidateQuotaUsage, invalidateSubscription, readBBParams, resolveMaxUsers, resolvePermissions, safeRedirect, saveAuthIntent, useAllQuotaUsage, useBillingPortal, useCancelSubscription, useCreateCheckoutSession, useInvoice, useInvoices, usePermissions, usePlanGroup, usePlanGroupVersions, usePublicPlanGroupVersion, usePublicPlans, usePushNotifications, useQuotaUsageContext, useQuotaUsageStatus, useRecordUsage, useResumeSubscription, useSaaSAuth, useSaaSOs, useSaaSSettings, useSaaSWorkspaces, useSeatStatus, useSubscription, useSubscriptionContext, useSubscriptionManagement, useTranslation, useTrialStatus, useUpdateSubscription, useUsageLogs, useUserAttributes, useUserFeatures, validateInvite, validateRedirectUrl };
-export type { BetaFormData, BetaFormResponse, BillingInterval, CheckoutResult, EventData, EventType, FormatQuotaWithPriceOptions, IAllQuotaUsageResponse, IBaseApiConfig, IBasePricing, IBetaConfig, ICheckoutSessionRequest, ICheckoutSessionResponse, ICheckoutStripeOptions, IEventCallbacks, IInvoice, IInvoiceListResponse, IInvoiceResponse, IOsConfig, IOsState, 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, NotificationData, NotificationEvent, NotificationResult, OnWorkspaceChangeParams, PermissionContext, PermissionKey, PlanVersionWithPricingVariants, PricingPageDetails, PricingPageProps, QuotaDisplayValue, QuotaDisplayWithOverage, QuotaUsageContextValue, RolePermissionMap, SDKLocale, SDKMessages, SaaSOSProviderProps, SeatStatus, SubscriptionContextValue, SubscriptionStatusType, TrialStatus, UserCreatedEventData, UserUpdatedEventData, WorkspaceChangedEventData, WorkspaceCreatedEventData, WorkspaceDeletedEventData, WorkspaceSettingsSection, WorkspaceUpdatedEventData, WorkspaceUserAddedEventData, WorkspaceUserRemovedEventData, WorkspaceUserRoleChangedEventData };
+export type { BetaFormData, BetaFormResponse, BillingInterval, CheckoutResult, EventData, EventType, FormatQuotaWithPriceOptions, GetCheckoutStripeParams, IAllQuotaUsageResponse, IBaseApiConfig, IBasePricing, IBetaConfig, ICheckoutSessionRequest, ICheckoutSessionResponse, ICheckoutStripeOptions, IEventCallbacks, IInvoice, IInvoiceListResponse, IInvoiceResponse, IOsConfig, IOsState, 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, NotificationData, NotificationEvent, NotificationResult, OnWorkspaceChangeParams, PermissionContext, PermissionKey, PlanVersionWithPricingVariants, PricingPageDetails, PricingPageProps, QuotaDisplayValue, QuotaDisplayWithOverage, QuotaUsageContextValue, RolePermissionMap, SDKLocale, SDKMessages, SaaSOSProviderProps, SeatStatus, SubscriptionContextValue, SubscriptionStatusType, TrialStatus, UserCreatedEventData, UserUpdatedEventData, WorkspaceChangedEventData, WorkspaceCreatedEventData, WorkspaceDeletedEventData, WorkspaceSettingsSection, WorkspaceUpdatedEventData, WorkspaceUserAddedEventData, WorkspaceUserRemovedEventData, WorkspaceUserRoleChangedEventData };