@buildbase/sdk 0.0.44 → 0.0.45

package/dist/react/index.d.ts

@@ -79,12 +79,14 @@ declare const InvoiceStatuses: {
     readonly Uncollectible: "uncollectible";
     readonly Void: "void";
 };
+type InvoiceStatusType = (typeof InvoiceStatuses)[keyof typeof InvoiceStatuses];
 /** Subscription item type constants */
 declare const SubscriptionItemType: {
     readonly Feature: "feature";
     readonly Limit: "limit";
     readonly Quota: "quota";
 };
+type SubscriptionItemTypeValue = (typeof SubscriptionItemType)[keyof typeof SubscriptionItemType];
 /** Dunning state constants */
 declare const DunningState: {
     readonly None: "none";
@@ -93,11 +95,14 @@ declare const DunningState: {
     readonly Final: "final";
     readonly Suspended: "suspended";
 };
+type DunningStateType = (typeof DunningState)[keyof typeof DunningState];
 interface ISubscription {
     _id: string;
     subscriptionStatus: SubscriptionStatusType;
     stripePriceId?: string;
     stripeCurrentPeriodEnd?: string;
+    /** When the current monthly usage period ends (quotas reset on this date). */
+    usageCurrentPeriodEnd?: string;
     cancelAtPeriodEnd: boolean;
     billingInterval?: BillingInterval;
     /** Trial start date (ISO string). Set when subscription is in trial. */
@@ -217,6 +222,21 @@ interface IPlanVersion {
         durationDays: number;
         requireCard: boolean;
     };
+    /** Credit grant configuration. When enabled, credits are granted to workspaces on this plan. */
+    creditGrant?: {
+        enabled: boolean;
+        /** Linked credit package (populated with name, slug, creditAmount). */
+        creditPackage?: {
+            _id: string;
+            name: string;
+            slug: string;
+            creditAmount: number;
+        } | string;
+        /** How unused plan credits are handled on renewal: 'reset' = expire old, 'topup' = add to existing. */
+        mode: 'reset' | 'topup';
+        /** true = credits given fresh every month, false = one-time lifetime grant (default). */
+        renewOnPeriod?: boolean;
+    };
     isCurrent?: boolean;
     isLegacy?: boolean;
     archived?: boolean;
@@ -485,6 +505,15 @@ interface IPublicPlanVersion {
         durationDays: number;
         requireCard: boolean;
     };
+    /** Credit grant config. Only present when the plan grants credits. */
+    creditGrant?: {
+        enabled: boolean;
+        creditAmount: number | null;
+        packageName: string | null;
+        mode: 'reset' | 'topup';
+        /** true = credits given fresh every month, false = one-time lifetime grant. */
+        renewOnPeriod: boolean;
+    };
 }
 interface IPublicPlansResponse {
     items: IPublicPlanItem[];
@@ -580,6 +609,166 @@ interface IUsageLogsResponse {
     hasNextPage: boolean;
     hasPrevPage: boolean;
 }
+/** Credit bucket source (how credits entered the workspace) */
+declare const CreditBucketSource: {
+    readonly PlanGrant: "plan_grant";
+    readonly CreditPackPurchase: "credit_pack_purchase";
+    readonly AdminGrant: "admin_grant";
+    readonly Refund: "refund";
+};
+type CreditBucketSourceType = (typeof CreditBucketSource)[keyof typeof CreditBucketSource];
+/** Credit bucket status */
+declare const CreditBucketStatus: {
+    readonly Pending: "pending";
+    readonly Active: "active";
+    readonly Expired: "expired";
+    readonly Consumed: "consumed";
+};
+type CreditBucketStatusType = (typeof CreditBucketStatus)[keyof typeof CreditBucketStatus];
+/** Credit transaction type */
+declare const CreditTransactionType: {
+    readonly PlanGrant: "plan_grant";
+    readonly PackPurchased: "pack_purchased";
+    readonly Consumed: "consumed";
+    readonly Expired: "expired";
+    readonly AdminGrant: "admin_grant";
+    readonly AdminRevoke: "admin_revoke";
+    readonly Refund: "refund";
+};
+type CreditTransactionTypeValue = (typeof CreditTransactionType)[keyof typeof CreditTransactionType];
+/** Credit balance for a workspace */
+interface ICreditBalance {
+    available: number;
+    totalGranted: number;
+    totalConsumed: number;
+    totalExpired: number;
+    totalRefunded: number;
+}
+/** Pricing variant for a credit package */
+interface ICreditPackagePricingVariant {
+    currency: string;
+    /** Price in smallest currency unit (cents) */
+    amount: number;
+    stripePriceId?: string;
+}
+/** Admin-defined purchasable credit package */
+interface ICreditPackage extends IDocument {
+    name: string;
+    slug: string;
+    description?: string;
+    creditAmount: number;
+    pricingVariants: ICreditPackagePricingVariant[];
+    validityDays?: number;
+    isActive: boolean;
+    sortOrder: number;
+    archived: boolean;
+}
+/** A single credit transaction (user-facing event history) */
+interface ICreditTransaction extends IDocument {
+    workspace: string;
+    type: CreditTransactionTypeValue;
+    /** Positive for grants, negative for consume/expire/revoke */
+    amount: number;
+    balanceAfter: number;
+    description?: string;
+    bucket?: string;
+    creditPackage?: string;
+    actor?: string;
+    metadata?: Record<string, any>;
+}
+/** A credit bucket (per-grant allocation with expiry) */
+interface ICreditBucket extends IDocument {
+    workspace: string;
+    source: CreditBucketSourceType;
+    status: CreditBucketStatusType;
+    creditAmount: number;
+    remaining: number;
+    expiresAt?: string;
+    activatedAt?: string;
+    creditPackage?: string | ICreditPackage;
+    grantedBy?: string;
+    metadata?: Record<string, any>;
+}
+/** Request body for POST .../credits/consume */
+interface IConsumeCreditsRequest {
+    amount: number;
+    description?: string;
+    idempotencyKey?: string;
+    metadata?: Record<string, any>;
+}
+/** Response from POST .../credits/consume */
+interface IConsumeCreditsResponse {
+    success: boolean;
+    consumed: number;
+    balanceAfter: number;
+}
+/** Request body for POST .../credits/purchase */
+interface ICreditPurchaseRequest {
+    creditPackageId: string;
+    currency?: string;
+    successUrl: string;
+    cancelUrl: string;
+}
+/** Response from POST .../credits/purchase */
+interface ICreditPurchaseResponse {
+    sessionId: string;
+    url: string;
+}
+/** Query params for GET .../credits/transactions */
+interface ICreditTransactionsQuery {
+    type?: CreditTransactionTypeValue;
+    page?: number;
+    limit?: number;
+}
+/** Paginated response from GET .../credits/transactions */
+interface ICreditTransactionsResponse {
+    docs: ICreditTransaction[];
+    totalDocs: number;
+    limit: number;
+    page: number;
+    totalPages: number;
+    hasNextPage: boolean;
+    hasPrevPage: boolean;
+}
+/** Query params for GET .../credits/buckets */
+interface ICreditBucketsQuery {
+    status?: CreditBucketStatusType;
+    source?: CreditBucketSourceType;
+    page?: number;
+    limit?: number;
+}
+/** Paginated response from GET .../credits/buckets */
+interface ICreditBucketsResponse {
+    docs: ICreditBucket[];
+    totalDocs: number;
+    limit: number;
+    page: number;
+    totalPages: number;
+    hasNextPage: boolean;
+    hasPrevPage: boolean;
+}
+/** Response from GET .../credits/expiring */
+interface IExpiringCreditsResponse {
+    days: number;
+    expiringCredits: number;
+    buckets: ICreditBucket[];
+}
+/** Public credit package (from public endpoint, no auth) */
+interface IPublicCreditPackage {
+    _id: string;
+    name: string;
+    slug: string;
+    description: string;
+    creditAmount: number;
+    pricingVariants: ICreditPackagePricingVariant[];
+    validityDays: number | null;
+    sortOrder: number;
+}
+/** Response from GET /:orgId/credit-packages (public, no auth) */
+interface IPublicCreditPackagesResponse {
+    packages: IPublicCreditPackage[];
+    notes?: string;
+}
 
 interface IWorkspace {
     _id: string;
@@ -1184,6 +1373,14 @@ declare class WorkspaceApi extends BaseApi {
      * @returns Plan group versions response with currentVersion and availableVersions
      */
     getPublicPlans(slug: string): Promise<IPublicPlansResponse>;
+    /**
+     * Get credit packages (public, no auth required).
+     * Returns active credit packages for the org with pricing info.
+     * Use this for public credit store pages.
+     *
+     * @returns Credit packages with pricing variants
+     */
+    getPublicCreditPackages(): Promise<IPublicCreditPackagesResponse>;
     /**
      * Get plan group version details by ID (public, no auth required).
      * Returns the full plan group version with populated plan versions.
@@ -1343,6 +1540,56 @@ declare class WorkspaceApi extends BaseApi {
         email?: boolean;
         push?: boolean;
     }>>;
+    /**
+     * Get credit balance for a workspace.
+     * @param workspaceId - The workspace ID
+     * @returns Credit balance with available, totalGranted, totalConsumed, totalExpired, totalRefunded
+     */
+    getCreditBalance(workspaceId: string): Promise<ICreditBalance>;
+    /**
+     * Consume credits from a workspace balance.
+     * Throws an error with `code: 'INSUFFICIENT_CREDITS'` and `available`/`requested` fields on 402.
+     * @param workspaceId - The workspace ID
+     * @param request - Consume request with amount, optional description, idempotencyKey, metadata
+     * @returns Consume result with consumed amount and balanceAfter
+     */
+    consumeCredits(workspaceId: string, request: IConsumeCreditsRequest): Promise<IConsumeCreditsResponse>;
+    /**
+     * Create a Stripe checkout session for purchasing a credit package.
+     * Returns a checkout URL to redirect the user to.
+     * @param workspaceId - The workspace ID
+     * @param request - Purchase request with creditPackageId, successUrl, cancelUrl, optional currency
+     * @returns Checkout session ID and URL
+     */
+    purchaseCredits(workspaceId: string, request: ICreditPurchaseRequest): Promise<ICreditPurchaseResponse>;
+    /**
+     * List available credit packages for purchase.
+     * Returns active, non-archived packages sorted by sortOrder then creditAmount.
+     * @param workspaceId - The workspace ID
+     * @returns Array of credit packages
+     */
+    getCreditPackages(workspaceId: string): Promise<ICreditPackage[]>;
+    /**
+     * Get paginated credit transaction history.
+     * @param workspaceId - The workspace ID
+     * @param query - Optional filters: type, page, limit
+     * @returns Paginated credit transactions
+     */
+    getCreditTransactions(workspaceId: string, query?: ICreditTransactionsQuery): Promise<ICreditTransactionsResponse>;
+    /**
+     * Get paginated credit buckets.
+     * @param workspaceId - The workspace ID
+     * @param query - Optional filters: status, source, page, limit
+     * @returns Paginated credit buckets
+     */
+    getCreditBuckets(workspaceId: string, query?: ICreditBucketsQuery): Promise<ICreditBucketsResponse>;
+    /**
+     * Get credits expiring within N days.
+     * @param workspaceId - The workspace ID
+     * @param days - Look-ahead window in days (1-90, default 7)
+     * @returns Expiring credits summary with bucket list
+     */
+    getExpiringCredits(workspaceId: string, days?: number): Promise<IExpiringCreditsResponse>;
 }
 
 /**
@@ -1424,6 +1671,12 @@ declare class EventEmitter {
 }
 declare const eventEmitter: EventEmitter;
 
+/**
+ * Notify all subscribers to refetch credit balance (e.g. after consume or purchase).
+ * Called internally by useConsumeCredits, usePurchaseCredits on success.
+ */
+declare function invalidateCreditBalance(): void;
+
 /**
  * Notify all subscribers to refetch quota usage (e.g. after recording usage).
  * Called internally by useRecordUsage on success.
@@ -1468,6 +1721,37 @@ declare function invalidateSubscription(): void;
  */
 /** The single URL param name used by the SDK */
 declare const BB_PARAM = "bb";
+/** BB param action values */
+declare const BBAction: {
+    readonly Checkout: "checkout";
+    readonly Billing: "billing";
+    readonly SelectPlan: "selectPlan";
+    readonly CreditPurchase: "creditPurchase";
+    readonly OpenCreditStore: "openCreditStore";
+    readonly Invite: "invite";
+};
+type BBActionType = (typeof BBAction)[keyof typeof BBAction];
+/** BB param status values */
+declare const BBStatus: {
+    readonly Success: "success";
+    readonly Cancel: "cancel";
+    readonly Error: "error";
+};
+type BBStatusType = (typeof BBStatus)[keyof typeof BBStatus];
+/** BB param screen values (mirrors SettingsScreen but avoids cross-layer import) */
+declare const BBScreen: {
+    readonly Subscription: "subscription";
+    readonly Credits: "credits";
+    readonly Usage: "usage";
+    readonly Users: "users";
+    readonly Profile: "profile";
+    readonly General: "general";
+    readonly Features: "features";
+    readonly Notifications: "notifications";
+    readonly Permissions: "permissions";
+    readonly Danger: "danger";
+};
+type BBScreenType = (typeof BBScreen)[keyof typeof BBScreen];
 /**
  * Build a URL with BuildBase params.
  *
@@ -1495,6 +1779,14 @@ declare function createCheckoutRedirectUrls(workspaceId: string, baseUrl?: strin
     successUrl: string;
     cancelUrl: string;
 };
+/**
+ * Build success + cancel URL pair for credit purchase checkout redirects.
+ * Both include the workspace ID and screen:credits.
+ */
+declare function createCreditPurchaseRedirectUrls(workspaceId: string, baseUrl?: string): {
+    successUrl: string;
+    cancelUrl: string;
+};
 /**
  * Read the `bb` param from the current URL.
  * Returns null if no `bb` param is present.
@@ -1879,6 +2171,7 @@ interface SDKMessages {
             users: string;
             subscription: string;
             usage: string;
+            credits: string;
             features: string;
             notifications: string;
             permissions: string;
@@ -1892,6 +2185,7 @@ interface SDKMessages {
             users: string;
             subscription: string;
             usage: string;
+            credits: string;
             features: string;
             notifications: string;
             permissions: string;
@@ -1992,6 +2286,17 @@ interface SDKMessages {
             features: string;
             limits: string;
             quotas: string;
+            credits: string;
+            creditsPerMonth: string;
+            creditsOneTime: string;
+            creditRenewal: string;
+            creditModeReset: string;
+            creditModeTopup: string;
+            creditModeLifetime: string;
+            /** @deprecated */
+            creditsPerPeriod: string;
+            /** @deprecated */
+            creditRollover: string;
         };
         checkout: {
             upgrade: string;
@@ -2357,6 +2662,50 @@ interface SDKMessages {
         saving: string;
         saveSuccess: string;
     };
+    credits: {
+        title: string;
+        description: string;
+        balance: string;
+        available: string;
+        totalGranted: string;
+        totalConsumed: string;
+        totalExpired: string;
+        noCredits: string;
+        noCreditsHint: string;
+        buyCredits: string;
+        buyAmount: string;
+        purchasing: string;
+        packages: string;
+        noPackages: string;
+        creditsAmount: string;
+        validityDays: string;
+        validityUnlimited: string;
+        transactions: string;
+        noTransactions: string;
+        loadMore: string;
+        viewAll: string;
+        expiringSoon: string;
+        expiringInDays: string;
+        noExpiring: string;
+        type: {
+            plan_grant: string;
+            pack_purchased: string;
+            consumed: string;
+            expired: string;
+            admin_grant: string;
+            admin_revoke: string;
+            refund: string;
+        };
+        dialogTitle: string;
+        dialogDescription: string;
+        dialogDescriptionWorkspace: string;
+        perCredit: string;
+        purchaseSuccess: string;
+        purchaseCanceled: string;
+        purchaseFailed: string;
+        errorLoading: string;
+        insufficientCredits: string;
+    };
     errors: {
         networkError: string;
         unauthorized: string;
@@ -2378,6 +2727,12 @@ interface SDKMessages {
         fetchQuotaUsage: string;
         fetchAllQuotaUsage: string;
         fetchUsageLogs: string;
+        fetchCreditBalance: string;
+        consumeCredits: string;
+        purchaseCredits: string;
+        fetchCreditPackages: string;
+        fetchCreditTransactions: string;
+        fetchExpiringCredits: string;
     };
 }
 /** Supported locale codes */
@@ -2566,6 +2921,7 @@ declare const SettingsScreen: {
     readonly Users: "users";
     readonly Subscription: "subscription";
     readonly Usage: "usage";
+    readonly Credits: "credits";
     readonly Features: "features";
     readonly Notifications: "notifications";
     readonly Permissions: "permissions";
@@ -2579,6 +2935,8 @@ declare function useSaaSAuth(): {
     signIn: (returnUrl?: string) => Promise<void>;
     signOut: () => Promise<void>;
     openWorkspaceSettings: (section?: WorkspaceSettingsSection) => void;
+    openCreditStore: () => void;
+    openPlanPicker: () => void;
     isAuthenticated: boolean;
     isLoading: boolean;
     isRedirecting: boolean;
@@ -3172,6 +3530,292 @@ declare const WhenQuotaThreshold: {
     displayName: string;
 };
 
+interface CreditActionsDetails {
+    /** Current credit balance. Null while loading. */
+    balance: ICreditBalance | null;
+    /** Whether balance is loading. */
+    loading: boolean;
+    /** Available credit packages for purchase. */
+    packages: ICreditPackage[];
+    /** Whether packages are loading. */
+    packagesLoading: boolean;
+    /**
+     * Consume credits from the workspace balance.
+     * Throws with `code: 'INSUFFICIENT_CREDITS'` if balance is too low.
+     *
+     * @example
+     * ```ts
+     * try {
+     *   const result = await consume({ amount: 10, description: 'AI generation' });
+     *   console.log(`Balance: ${result.balanceAfter}`);
+     * } catch (err) {
+     *   if (err.code === 'INSUFFICIENT_CREDITS') showUpgradePrompt();
+     * }
+     * ```
+     */
+    consume: (request: IConsumeCreditsRequest) => Promise<IConsumeCreditsResponse>;
+    /** Whether a consume operation is in progress. */
+    consuming: boolean;
+    /**
+     * Purchase a credit package. Redirects to Stripe Checkout.
+     * On success, user returns to the app with the credits screen open.
+     *
+     * @example
+     * ```ts
+     * await purchase(packages[0]); // Redirects to Stripe
+     * ```
+     */
+    purchase: (pkg: ICreditPackage) => Promise<void>;
+    /** Whether a purchase redirect is in progress. */
+    purchasing: boolean;
+    /** Refetch the balance. */
+    refetch: () => Promise<void>;
+    /** Error from the last consume or purchase operation. */
+    error: string | null;
+}
+interface CreditActionsProviderProps {
+    /** Render prop receiving credit actions — build your own UI. */
+    children: (details: CreditActionsDetails) => React.ReactNode;
+}
+/**
+ * Provides credit balance, packages, and action functions (consume, purchase) via render prop.
+ * Must be inside SaaSOSProvider. Handles Stripe redirect URLs automatically.
+ *
+ * @example
+ * ```tsx
+ * <CreditActionsProvider>
+ *   {({ balance, packages, consume, purchase, consuming, purchasing }) => (
+ *     <div>
+ *       <p>{balance?.available ?? 0} credits</p>
+ *
+ *       <button onClick={() => consume({ amount: 5 })} disabled={consuming}>
+ *         Use 5 Credits
+ *       </button>
+ *
+ *       {packages.map(pkg => (
+ *         <button key={pkg._id} onClick={() => purchase(pkg)} disabled={purchasing}>
+ *           Buy {pkg.creditAmount} for ${pkg.pricingVariants[0]?.amount / 100}
+ *         </button>
+ *       ))}
+ *     </div>
+ *   )}
+ * </CreditActionsProvider>
+ * ```
+ */
+declare const CreditActionsProvider: {
+    ({ children }: CreditActionsProviderProps): react.ReactNode;
+    displayName: string;
+};
+
+interface CreditBalanceDetails {
+    /** Credit balance data. Null while loading or if no workspace. */
+    balance: ICreditBalance | null;
+    /** Whether data is being fetched. */
+    loading: boolean;
+    /** Error message if fetch failed. */
+    error: string | null;
+    /** Manually refresh the balance. */
+    refetch: () => Promise<void>;
+}
+interface CreditBalanceProps {
+    /** Render prop receiving balance details — build your own UI. */
+    children: (details: CreditBalanceDetails) => React.ReactNode;
+}
+/**
+ * Provides credit balance data for the current workspace via render prop.
+ * Must be inside SaaSOSProvider. Balance auto-updates after consume/purchase.
+ *
+ * @example
+ * ```tsx
+ * <CreditBalance>
+ *   {({ balance, loading }) => {
+ *     if (loading) return <Skeleton />;
+ *     return <span>{balance?.available ?? 0} credits</span>;
+ *   }}
+ * </CreditBalance>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Navbar credit indicator
+ * <CreditBalance>
+ *   {({ balance, loading, refetch }) => (
+ *     <button onClick={refetch} disabled={loading}>
+ *       <CoinIcon />
+ *       {loading ? '...' : balance?.available ?? 0}
+ *     </button>
+ *   )}
+ * </CreditBalance>
+ * ```
+ */
+declare const CreditBalance: {
+    ({ children }: CreditBalanceProps): react.ReactNode;
+    displayName: string;
+};
+
+interface CreditStorePageDetails {
+    /** Whether package data is being fetched */
+    loading: boolean;
+    /** Error message if fetch failed */
+    error: string | null;
+    /** Available credit packages with pricing */
+    packages: IPublicCreditPackage[];
+    /** Optional note from API (e.g. "Pricing is in cents.") */
+    notes?: string;
+    /** Refetch package data */
+    refetch: () => Promise<void>;
+    /**
+     * Select a package to purchase. Handles everything automatically:
+     * - If authenticated → opens the workspace settings Credits tab
+     * - If not authenticated → saves a redirect URL and triggers sign-in
+     *
+     * @example
+     * ```tsx
+     * <button onClick={() => selectPackage(pkg._id)}>
+     *   Buy {pkg.creditAmount} Credits
+     * </button>
+     * ```
+     */
+    selectPackage: (packageId: string) => void;
+}
+interface CreditStorePageProps {
+    /** Render prop receiving package details — build your own credit store UI */
+    children: (details: CreditStorePageDetails) => ReactNode;
+    /** Custom loading UI. Defaults to skeleton. */
+    loadingFallback?: ReactNode;
+    /** Custom error UI. Receives error message. */
+    errorFallback?: (error: string) => ReactNode;
+    /**
+     * Base URL for post-login redirects (e.g. `"https://app.com/dashboard"`).
+     * When set, `selectPackage()` can redirect unauthenticated users through login
+     * and back to the dashboard with the credits screen open.
+     */
+    redirectBaseUrl?: string;
+}
+/**
+ * Fetches and provides credit package details for public credit store pages (no login required).
+ * Returns packages with pricing — the consumer constructs the layout.
+ * Similar to `<PricingPage>` but for credit packages.
+ *
+ * @example
+ * ```tsx
+ * <CreditStorePage redirectBaseUrl="https://app.com/dashboard">
+ *   {({ loading, error, packages, selectPackage }) => {
+ *     if (loading) return <Loading />;
+ *     if (error) return <Error message={error} />;
+ *
+ *     return (
+ *       <div className="grid grid-cols-3 gap-4">
+ *         {packages.map(pkg => (
+ *           <div key={pkg._id}>
+ *             <h3>{pkg.name}</h3>
+ *             <p>{pkg.creditAmount} credits</p>
+ *             <p>${(pkg.pricingVariants[0]?.amount / 100).toFixed(2)}</p>
+ *             <button onClick={() => selectPackage(pkg._id)}>Buy</button>
+ *           </div>
+ *         ))}
+ *       </div>
+ *     );
+ *   }}
+ * </CreditStorePage>
+ * ```
+ */
+declare function CreditStorePage({ children, loadingFallback, errorFallback, redirectBaseUrl, }: CreditStorePageProps): react_jsx_runtime.JSX.Element;
+
+interface IWhenCreditsProps {
+    /** Content to render when the condition is met. */
+    children: React.ReactNode;
+    /** Optional component/element to show while credit balance is loading (e.g. <Skeleton />). */
+    loadingComponent?: React.ReactNode;
+    /** Optional component/element to show when condition is not met (e.g. <BuyCreditsPrompt />). */
+    fallbackComponent?: React.ReactNode;
+}
+interface IWhenCreditsAvailableProps extends IWhenCreditsProps {
+    /** Minimum credits required to render children. Default: 1 */
+    min?: number;
+}
+interface IWhenCreditsLowProps extends IWhenCreditsProps {
+    /** Credits threshold. Children render when available <= threshold. */
+    threshold: number;
+}
+/**
+ * Renders children only when the workspace has at least `min` credits available.
+ * Must be used within CreditBalanceContextProvider (included in SaaSOSProvider by default).
+ *
+ * @example
+ * ```tsx
+ * <WhenCreditsAvailable min={10}>
+ *   <GenerateButton />
+ * </WhenCreditsAvailable>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * <WhenCreditsAvailable
+ *   min={5}
+ *   loadingComponent={<Skeleton />}
+ *   fallbackComponent={<p>Not enough credits. <BuyCreditsLink /></p>}
+ * >
+ *   <AIFeature />
+ * </WhenCreditsAvailable>
+ * ```
+ */
+declare const WhenCreditsAvailable: {
+    (props: IWhenCreditsAvailableProps): react.ReactNode;
+    displayName: string;
+};
+/**
+ * Renders children only when the workspace has zero credits available.
+ * Must be used within CreditBalanceContextProvider (included in SaaSOSProvider by default).
+ *
+ * @example
+ * ```tsx
+ * <WhenCreditsExhausted>
+ *   <BuyCreditsPrompt message="You're out of credits!" />
+ * </WhenCreditsExhausted>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * <WhenCreditsExhausted
+ *   loadingComponent={<Spinner />}
+ *   fallbackComponent={null}
+ * >
+ *   <NoCreditsOverlay />
+ * </WhenCreditsExhausted>
+ * ```
+ */
+declare const WhenCreditsExhausted: {
+    (props: IWhenCreditsProps): react.ReactNode;
+    displayName: string;
+};
+/**
+ * Renders children when credits are at or below a threshold.
+ * Must be used within CreditBalanceContextProvider (included in SaaSOSProvider by default).
+ *
+ * @example
+ * ```tsx
+ * <WhenCreditsLow threshold={50}>
+ *   <p>Running low on credits! Consider buying more.</p>
+ * </WhenCreditsLow>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * <WhenCreditsLow
+ *   threshold={10}
+ *   loadingComponent={<Skeleton />}
+ *   fallbackComponent={null}
+ * >
+ *   <LowCreditsBanner />
+ * </WhenCreditsLow>
+ * ```
+ */
+declare const WhenCreditsLow: {
+    (props: IWhenCreditsLowProps): react.ReactNode;
+    displayName: string;
+};
+
 /**
  * Value provided by SubscriptionContext and returned by useSubscriptionContext.
  */
@@ -3242,6 +3886,35 @@ declare const QuotaUsageContextProvider: react__default.FC<{
  */
 declare function useQuotaUsageContext(): QuotaUsageContextValue;
 
+interface CreditBalanceContextValue {
+    /** Credit balance for the current workspace. Null if not loaded or no workspace. */
+    balance: ICreditBalance | null;
+    /** Whether the balance is being fetched. */
+    loading: boolean;
+    /** Error message if the fetch failed. */
+    error: string | null;
+    /** Manually refetch the credit balance. */
+    refetch: () => Promise<void>;
+}
+
+/**
+ * Provides credit balance data for the current workspace to credit gate components.
+ * Fetches when workspace changes; refetches when credit balance is invalidated
+ * (e.g. after consume or purchase).
+ * Included in SaaSOSProvider by default.
+ */
+declare const CreditBalanceContextProvider: react__default.FC<{
+    children: ReactNode;
+}>;
+/**
+ * Returns credit balance data for the current workspace.
+ * Must be used within CreditBalanceContextProvider (included in SaaSOSProvider by default).
+ *
+ * @returns CreditBalanceContextValue - { balance, loading, error, refetch }
+ * @throws Error if used outside CreditBalanceContextProvider
+ */
+declare function useCreditBalanceContext(): CreditBalanceContextValue;
+
 /**
  * Hook to access OS (organization) state (serverUrl, version, orgId, auth, settings).
  * Prefer useSaaSSettings() when you only need settings.
@@ -4157,6 +4830,239 @@ declare const useUsageLogs: (workspaceId: string | null | undefined, quotaSlug?:
     refetch: () => Promise<void>;
 };
 
+/**
+ * Hook to get the credit balance for a workspace.
+ * Automatically fetches when workspaceId changes.
+ *
+ * @param workspaceId - The workspace ID. Can be null/undefined to disable fetching.
+ * @returns { balance, loading, error, refetch }
+ *
+ * @example
+ * ```tsx
+ * function CreditDisplay() {
+ *   const { currentWorkspace } = useSaaSWorkspaces();
+ *   const { balance, loading } = useCreditBalance(currentWorkspace?._id);
+ *
+ *   if (loading) return <Loading />;
+ *   if (!balance) return null;
+ *
+ *   return <p>{balance.available} credits available</p>;
+ * }
+ * ```
+ */
+declare const useCreditBalance: (workspaceId: string | null | undefined) => {
+    balance: ICreditBalance | null;
+    loading: boolean;
+    error: string | null;
+    refetch: () => Promise<void>;
+};
+/**
+ * Hook to consume credits from a workspace balance.
+ * Returns a mutation function. Throws with `code: 'INSUFFICIENT_CREDITS'` on 402.
+ *
+ * @param workspaceId - The workspace ID. Can be null/undefined.
+ * @returns { consumeCredits, loading, error }
+ *
+ * @example
+ * ```tsx
+ * function GenerateButton() {
+ *   const { currentWorkspace } = useSaaSWorkspaces();
+ *   const { consumeCredits, loading } = useConsumeCredits(currentWorkspace?._id);
+ *
+ *   const handleGenerate = async () => {
+ *     try {
+ *       const result = await consumeCredits({
+ *         amount: 10,
+ *         description: 'AI image generation',
+ *         idempotencyKey: `gen-${crypto.randomUUID()}`,
+ *       });
+ *       console.log(`Balance after: ${result.balanceAfter}`);
+ *     } catch (err: any) {
+ *       if (err.code === 'INSUFFICIENT_CREDITS') {
+ *         alert(`Not enough credits. Available: ${err.available}`);
+ *       }
+ *     }
+ *   };
+ *
+ *   return <button onClick={handleGenerate} disabled={loading}>Generate</button>;
+ * }
+ * ```
+ */
+declare const useConsumeCredits: (workspaceId: string | null | undefined) => {
+    consumeCredits: (request: IConsumeCreditsRequest) => Promise<IConsumeCreditsResponse>;
+    loading: boolean;
+    error: string | null;
+};
+/**
+ * Hook to create a Stripe checkout session for purchasing a credit package.
+ * Returns a mutation function that resolves with { sessionId, url }.
+ *
+ * @param workspaceId - The workspace ID. Can be null/undefined.
+ * @returns { purchaseCredits, loading, error }
+ *
+ * @example
+ * ```tsx
+ * function BuyCreditsButton({ packageId }) {
+ *   const { currentWorkspace } = useSaaSWorkspaces();
+ *   const { purchaseCredits, loading } = usePurchaseCredits(currentWorkspace?._id);
+ *
+ *   const handleBuy = async () => {
+ *     const result = await purchaseCredits({
+ *       creditPackageId: packageId,
+ *       successUrl: `${window.location.origin}/credits/success`,
+ *       cancelUrl: `${window.location.origin}/credits`,
+ *     });
+ *     window.location.href = result.url;
+ *   };
+ *
+ *   return <button onClick={handleBuy} disabled={loading}>Buy Credits</button>;
+ * }
+ * ```
+ */
+declare const usePurchaseCredits: (workspaceId: string | null | undefined) => {
+    purchaseCredits: (request: ICreditPurchaseRequest) => Promise<ICreditPurchaseResponse>;
+    loading: boolean;
+    error: string | null;
+};
+/**
+ * Hook to list available credit packages for purchase.
+ * Automatically fetches when workspaceId changes.
+ *
+ * @param workspaceId - The workspace ID. Can be null/undefined to disable fetching.
+ * @returns { packages, loading, error, refetch }
+ *
+ * @example
+ * ```tsx
+ * function CreditStore() {
+ *   const { currentWorkspace } = useSaaSWorkspaces();
+ *   const { packages, loading } = useCreditPackages(currentWorkspace?._id);
+ *
+ *   if (loading) return <Loading />;
+ *
+ *   return (
+ *     <div>
+ *       {packages.map(pkg => (
+ *         <div key={pkg._id}>
+ *           <h3>{pkg.name}</h3>
+ *           <p>{pkg.creditAmount} credits</p>
+ *         </div>
+ *       ))}
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+declare const useCreditPackages: (workspaceId: string | null | undefined) => {
+    packages: ICreditPackage[];
+    loading: boolean;
+    error: string | null;
+    refetch: () => Promise<void>;
+};
+/**
+ * Hook to get paginated credit transaction history.
+ * Automatically fetches when workspaceId or query params change.
+ *
+ * @param workspaceId - The workspace ID. Can be null/undefined to disable fetching.
+ * @param query - Optional filters: type, page, limit
+ * @returns { transactions, totalDocs, totalPages, page, hasNextPage, hasPrevPage, loading, error, refetch }
+ *
+ * @example
+ * ```tsx
+ * function TransactionHistory() {
+ *   const { currentWorkspace } = useSaaSWorkspaces();
+ *   const { transactions, totalPages, page, loading } = useCreditTransactions(
+ *     currentWorkspace?._id,
+ *     { limit: 20 }
+ *   );
+ *
+ *   if (loading) return <Loading />;
+ *
+ *   return (
+ *     <div>
+ *       {transactions.map(tx => (
+ *         <div key={tx._id}>
+ *           {tx.type}: {tx.amount} (balance: {tx.balanceAfter})
+ *         </div>
+ *       ))}
+ *       <p>Page {page} of {totalPages}</p>
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+declare const useCreditTransactions: (workspaceId: string | null | undefined, query?: ICreditTransactionsQuery) => {
+    transactions: ICreditTransaction[];
+    totalDocs: number;
+    totalPages: number;
+    page: number;
+    hasNextPage: boolean;
+    hasPrevPage: boolean;
+    loading: boolean;
+    error: string | null;
+    refetch: () => Promise<void>;
+};
+/**
+ * Hook to get credits expiring within N days.
+ * Automatically fetches when workspaceId or days changes.
+ *
+ * @param workspaceId - The workspace ID. Can be null/undefined to disable fetching.
+ * @param days - Look-ahead window in days (1-90, default 7)
+ * @returns { expiringCredits, buckets, days, loading, error, refetch }
+ *
+ * @example
+ * ```tsx
+ * function ExpiringCreditsWarning() {
+ *   const { currentWorkspace } = useSaaSWorkspaces();
+ *   const { expiringCredits, loading } = useExpiringCredits(currentWorkspace?._id, 7);
+ *
+ *   if (loading || expiringCredits === 0) return null;
+ *
+ *   return <p>Warning: {expiringCredits} credits expire within 7 days</p>;
+ * }
+ * ```
+ */
+declare const useExpiringCredits: (workspaceId: string | null | undefined, days?: number) => {
+    expiringCredits: number;
+    buckets: ICreditBucket[];
+    days: number;
+    loading: boolean;
+    error: string | null;
+    refetch: () => Promise<void>;
+};
+/**
+ * Hook to fetch credit packages publicly (no auth required).
+ * Uses orgId from SaaSOSProvider — must be inside the provider.
+ *
+ * @returns { packages, notes, loading, error, refetch }
+ *
+ * @example
+ * ```tsx
+ * function CreditStore() {
+ *   const { packages, loading } = usePublicCreditPackages();
+ *
+ *   if (loading) return <Loading />;
+ *
+ *   return (
+ *     <div>
+ *       {packages.map(pkg => (
+ *         <div key={pkg._id}>
+ *           <h3>{pkg.name}</h3>
+ *           <p>{pkg.creditAmount} credits</p>
+ *         </div>
+ *       ))}
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+declare const usePublicCreditPackages: () => {
+    packages: IPublicCreditPackage[];
+    notes: string | undefined;
+    loading: boolean;
+    error: string | null;
+    refetch: () => Promise<void>;
+};
+
 interface TrialStatus {
     /** Whether the current subscription is in trial. */
     isTrialing: boolean;
@@ -4368,5 +5274,5 @@ 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, 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 };
+export { ApiVersion, AuthApi, AuthStatus, BBAction, BBScreen, BBStatus, BB_PARAM, BaseApi, BetaForm, BillingIntervals, CURRENCY_DISPLAY, CURRENCY_FLAG, CreditActionsProvider, CreditBalance, CreditBalanceContextProvider, CreditBucketSource, CreditBucketStatus, CreditStorePage, CreditTransactionType, 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, WhenCreditsAvailable, WhenCreditsExhausted, WhenCreditsLow, 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, createCreditPurchaseRedirectUrls, eventEmitter, formatCents, formatOverageRate, formatOverageRateWithLabel, formatQuotaIncludedOverage, formatQuotaWithPrice, getAvailableCurrenciesFromPlans, getBasePriceCents, getBillingIntervalAndCurrencyFromPriceId, getCurrencyFlag, getCurrencySymbol, getDisplayCurrency, getPerSeatPriceCents, getPricingVariant, getQuotaDisplayValue, getQuotaDisplayWithVariant, getQuotaOverageCents, getQuotaUnitLabelFromName, getSeatPricing, getStripePriceIdForInterval, hasPermission, invalidateCreditBalance, invalidateQuotaUsage, invalidateSubscription, readBBParams, resolveMaxUsers, resolvePermissions, safeRedirect, saveAuthIntent, useAllQuotaUsage, useBillingPortal, useCancelSubscription, useConsumeCredits, useCreateCheckoutSession, useCreditBalance, useCreditBalanceContext, useCreditPackages, useCreditTransactions, useExpiringCredits, useInvoice, useInvoices, usePermissions, usePlanGroup, usePlanGroupVersions, usePublicCreditPackages, usePublicPlanGroupVersion, usePublicPlans, usePurchaseCredits, usePushNotifications, useQuotaUsageContext, useQuotaUsageStatus, useRecordUsage, useResumeSubscription, useSaaSAuth, useSaaSOs, useSaaSSettings, useSaaSWorkspaces, useSeatStatus, useSubscription, useSubscriptionContext, useSubscriptionManagement, useTranslation, useTrialStatus, useUpdateSubscription, useUsageLogs, useUserAttributes, useUserFeatures, validateInvite, validateRedirectUrl };
+export type { BBActionType, BBScreenType, BBStatusType, BetaFormData, BetaFormResponse, BillingInterval, CheckoutResult, CreditActionsDetails, CreditBalanceContextValue, CreditBalanceDetails, CreditBucketSourceType, CreditBucketStatusType, CreditStorePageDetails, CreditTransactionTypeValue, DunningStateType, EventData, EventType, FormatQuotaWithPriceOptions, GetCheckoutStripeParams, IAllQuotaUsageResponse, IBaseApiConfig, IBasePricing, IBetaConfig, ICheckoutSessionRequest, ICheckoutSessionResponse, ICheckoutStripeOptions, IConsumeCreditsRequest, IConsumeCreditsResponse, ICreditBalance, ICreditBucket, ICreditBucketsQuery, ICreditBucketsResponse, ICreditPackage, ICreditPackagePricingVariant, ICreditPurchaseRequest, ICreditPurchaseResponse, ICreditTransaction, ICreditTransactionsQuery, ICreditTransactionsResponse, IEventCallbacks, IExpiringCreditsResponse, IInvoice, IInvoiceListResponse, IInvoiceResponse, IOsConfig, IOsState, IPlan, IPlanGroup, IPlanGroupInfo, IPlanGroupLatestVersion, IPlanGroupResponse, IPlanGroupVersion, IPlanGroupVersionWithPlans, IPlanGroupVersionsResponse, IPlanVersion, IPlanVersionSummary, IPlanVersionWithPlan, IPricingVariant, IPublicCreditPackage, IPublicCreditPackagesResponse, IPublicPlanItem, IPublicPlanItemCategory, IPublicPlanVersion, IPublicPlansResponse, IQuotaByInterval, IQuotaIntervalValue, IQuotaOveragePriceIdsByInterval, IQuotaOveragesByInterval, IQuotaUsageStatus, IQuotaUsageStatusResponse, IRecordUsageRequest, IRecordUsageResponse, IStripePricesByInterval, ISubscription, ISubscriptionItem, ISubscriptionResponse, ISubscriptionUpdateRequest, ISubscriptionUpdateResponse, IUsageLogEntry, IUsageLogsQuery, IUsageLogsResponse, InviteBlockReason, InviteValidation, InvoiceStatus, InvoiceStatusType, MaxUsersConfig, NotificationData, NotificationEvent, NotificationResult, OnWorkspaceChangeParams, PermissionContext, PermissionKey, PlanVersionWithPricingVariants, PricingPageDetails, PricingPageProps, QuotaDisplayValue, QuotaDisplayWithOverage, QuotaUsageContextValue, RolePermissionMap, SDKLocale, SDKMessages, SaaSOSProviderProps, SeatStatus, SubscriptionContextValue, SubscriptionItemTypeValue, SubscriptionStatusType, TrialStatus, UserCreatedEventData, UserUpdatedEventData, WorkspaceChangedEventData, WorkspaceCreatedEventData, WorkspaceDeletedEventData, WorkspaceSettingsSection, WorkspaceUpdatedEventData, WorkspaceUserAddedEventData, WorkspaceUserRemovedEventData, WorkspaceUserRoleChangedEventData };