@buildbase/sdk 0.0.31 → 0.0.32

package/dist/react/index.d.ts

@@ -1,4 +1,3 @@
-import { z } from 'zod';
 import * as react from 'react';
 import react__default, { ReactNode } from 'react';
 import * as react_jsx_runtime from 'react/jsx-runtime';
@@ -55,9 +54,48 @@ interface IAsset extends IDocument {
     creator: string | IUser;
 }
 type BillingInterval = 'monthly' | 'yearly' | 'quarterly';
+/** Billing interval constants */
+declare const BillingIntervals: {
+    readonly Monthly: "monthly";
+    readonly Yearly: "yearly";
+    readonly Quarterly: "quarterly";
+};
+/** Subscription status constants */
+declare const SubscriptionStatus: {
+    readonly Active: "active";
+    readonly Trialing: "trialing";
+    readonly Canceled: "canceled";
+    readonly PastDue: "past_due";
+    readonly Paused: "paused";
+    readonly Incomplete: "incomplete";
+    readonly Unpaid: "unpaid";
+};
+type SubscriptionStatusType = (typeof SubscriptionStatus)[keyof typeof SubscriptionStatus];
+/** Invoice status constants */
+declare const InvoiceStatuses: {
+    readonly Draft: "draft";
+    readonly Open: "open";
+    readonly Paid: "paid";
+    readonly Uncollectible: "uncollectible";
+    readonly Void: "void";
+};
+/** Subscription item type constants */
+declare const SubscriptionItemType: {
+    readonly Feature: "feature";
+    readonly Limit: "limit";
+    readonly Quota: "quota";
+};
+/** Dunning state constants */
+declare const DunningState: {
+    readonly None: "none";
+    readonly Notified: "notified";
+    readonly Warning: "warning";
+    readonly Final: "final";
+    readonly Suspended: "suspended";
+};
 interface ISubscription {
     _id: string;
-    subscriptionStatus: 'active' | 'trialing' | 'canceled' | 'past_due' | 'paused' | 'incomplete' | 'unpaid';
+    subscriptionStatus: SubscriptionStatusType;
     stripePriceId?: string;
     stripeCurrentPeriodEnd?: string;
     cancelAtPeriodEnd: boolean;
@@ -545,10 +583,19 @@ interface IWorkspaceUser {
     role: string;
 }
 
-/**
- * Event types for all SDK events
- */
-type EventType = 'user:created' | 'user:updated' | 'workspace:changed' | 'workspace:updated' | 'workspace:user-added' | 'workspace:user-removed' | 'workspace:user-role-changed' | 'workspace:created' | 'workspace:deleted';
+/** Event type constants */
+declare const SDKEvent: {
+    readonly UserCreated: "user:created";
+    readonly UserUpdated: "user:updated";
+    readonly WorkspaceChanged: "workspace:changed";
+    readonly WorkspaceUpdated: "workspace:updated";
+    readonly WorkspaceUserAdded: "workspace:user-added";
+    readonly WorkspaceUserRemoved: "workspace:user-removed";
+    readonly WorkspaceUserRoleChanged: "workspace:user-role-changed";
+    readonly WorkspaceCreated: "workspace:created";
+    readonly WorkspaceDeleted: "workspace:deleted";
+};
+type EventType = (typeof SDKEvent)[keyof typeof SDKEvent];
 /**
  * Event data types for each event
  */
@@ -654,6 +701,26 @@ interface IAuthCallbacks {
      * ```
      */
     getSession: () => Promise<string | null>;
+    /**
+     * Called when a session is missing, expired, or invalid.
+     * Use this to redirect to login, show a re-auth modal, or refresh the token.
+     *
+     * Triggers:
+     * - `getSession()` returns null on page refresh (cookie missing/expired)
+     * - `getProfile()` fails with 401 (session revoked server-side)
+     * - API call returns 401 during usage (session expired mid-session)
+     *
+     * @param reason - Why the session expired
+     *
+     * @example
+     * ```ts
+     * onSessionExpired: (reason) => {
+     *   console.log('Session expired:', reason);
+     *   router.push('/login');
+     * }
+     * ```
+     */
+    onSessionExpired?: (reason: 'missing' | 'expired' | 'invalid') => void;
     /**
      * Event handler for User and Workspace events
      * @param eventType - The type of event that occurred
@@ -673,12 +740,25 @@ interface OnWorkspaceChangeParams {
     role: string | null;
 }
 
+type WorkspaceMode = 'personal' | 'platform';
 interface ISettings {
     workspace: {
         roles: string[];
         defaultRole: string;
         maxWorkspaces: number;
         maxWorkspaceUsers: number;
+        /** Workspace mode: 'personal' (solo) or 'platform' (multi-user, default) */
+        mode: WorkspaceMode;
+        /** Whether users can create workspaces. false = disabled, 'owner-only' = restricted */
+        canCreateWorkspace: boolean | 'owner-only';
+        /** Whether members can invite others. false = disabled, 'admin-only' = restricted */
+        canInviteMembers: boolean | 'admin-only';
+        /** Show workspace switcher in the UI */
+        showSwitcher: boolean;
+        /** Max workspaces a user can own. 0 = unlimited */
+        maxWorkspacesPerUser: number;
+        /** Auto-create workspace on first login */
+        autoCreateFirst: boolean;
     };
     [key: string]: any;
 }
@@ -1033,6 +1113,41 @@ declare class WorkspaceApi extends BaseApi {
      * @returns Usage result with consumed/included/available/overage
      */
     recordUsage(workspaceId: string, request: IRecordUsageRequest): Promise<IRecordUsageResponse>;
+    /**
+     * Record multiple quota usage entries in a single request.
+     * Designed for backend-to-backend high-volume scenarios (bulk exports, batch jobs).
+     * Max 100 items per request.
+     *
+     * @example
+     * ```ts
+     * await api.recordUsageBatch(workspaceId, {
+     *   items: [
+     *     { quotaSlug: 'images', quantity: 500, source: 'batch-export' },
+     *     { quotaSlug: 'videos', quantity: 10, source: 'batch-export' },
+     *   ]
+     * });
+     * ```
+     */
+    recordUsageBatch(workspaceId: string, request: {
+        items: Array<{
+            quotaSlug: string;
+            quantity: number;
+            metadata?: Record<string, any>;
+            source?: string;
+            idempotencyKey?: string;
+        }>;
+    }): Promise<{
+        success: boolean;
+        total: number;
+        succeeded: number;
+        failed: number;
+        results: Array<{
+            success: boolean;
+            quotaSlug: string;
+            quantity: number;
+            error?: string;
+        }>;
+    }>;
     /**
      * Get usage status for a single quota
      * @param workspaceId - The workspace ID
@@ -1146,6 +1261,93 @@ declare function invalidateSubscription(): void;
  */
 declare function invalidateQuotaUsage(): void;
 
+/**
+ * BuildBase URL parameter utilities.
+ *
+ * Single URL param `bb` carries comma-separated key:value pairs.
+ * No collision with user's own URL params.
+ *
+ * Format: ?bb=key:value,key:value,key:value
+ *
+ * Reserved keys:
+ *   screen   → settings section to open (subscription, users, etc.)
+ *   ws       → workspace ID to switch to
+ *   action   → what triggered it (checkout, billing, invite, etc.)
+ *   status   → result status (success, cancel, error)
+ *
+ * @example
+ * ```ts
+ * import { createBBUrl, readBBParams, cleanBBParams } from '@buildbase/sdk'
+ *
+ * // After Stripe checkout
+ * const url = createBBUrl({ action: 'checkout', status: 'success', ws: workspaceId, screen: 'subscription' })
+ * // → https://app.com/dashboard?bb=action:checkout,status:success,ws:65abc,screen:subscription
+ *
+ * // Read on page load
+ * const params = readBBParams()
+ * // → { action: 'checkout', status: 'success', ws: '65abc', screen: 'subscription' }
+ *
+ * // Clean up
+ * cleanBBParams()
+ * ```
+ */
+/** The single URL param name used by the SDK */
+declare const BB_PARAM = "bb";
+/**
+ * Build a URL with BuildBase params.
+ *
+ * @param params - Key-value pairs to encode (screen, ws, action, status, or any custom key)
+ * @param baseUrl - Base URL (defaults to current page)
+ *
+ * @example
+ * ```ts
+ * // Stripe checkout redirect
+ * createBBUrl({ action: 'checkout', status: 'success', ws: workspaceId, screen: 'subscription' })
+ *
+ * // Direct link to settings
+ * createBBUrl({ screen: 'users' })
+ *
+ * // Custom data
+ * createBBUrl({ action: 'invite', ws: workspaceId, email: 'user@example.com' })
+ * ```
+ */
+declare function createBBUrl(params: Record<string, string>, baseUrl?: string): string;
+/**
+ * Build success + cancel URL pair for Stripe checkout redirects.
+ * Both include the workspace ID and screen:subscription.
+ */
+declare function createCheckoutRedirectUrls(workspaceId: string, baseUrl?: string): {
+    successUrl: string;
+    cancelUrl: string;
+};
+/**
+ * Read the `bb` param from the current URL.
+ * Returns null if no `bb` param is present.
+ * Returns a plain object of key-value pairs.
+ *
+ * Common keys: screen, ws, action, status
+ */
+declare function readBBParams(): Record<string, string> | null;
+/**
+ * Remove the `bb` param from the current URL without triggering navigation.
+ */
+declare function cleanBBParams(): void;
+
+/**
+ * Security utilities for the SDK.
+ */
+/**
+ * Validate that a URL is safe to redirect to.
+ * Prevents open redirect attacks by ensuring the URL uses https (or http on localhost).
+ * Returns the URL if safe, or null if not.
+ */
+declare function validateRedirectUrl(url: string | null | undefined): string | null;
+/**
+ * Safely redirect to a URL after validating it.
+ * Falls back to fallbackUrl if the target URL is invalid.
+ */
+declare function safeRedirect(url: string | null | undefined, fallbackUrl?: string): void;
+
 /**
  * Centralized formatting for subscription/quota display: cents, overage rates, included + overage text.
  * Currency must be provided by the caller (e.g. workspace.billingCurrency, plan.currency, or selected currency).
@@ -1167,29 +1369,41 @@ declare const PLAN_CURRENCY_OPTIONS: {
 }[];
 /** Format cents as money string (e.g. 1999, "usd" -> "$19.99"). Caller must pass currency (e.g. from plan or workspace). */
 declare function formatCents(cents: number, currency: string): string;
+/** Translatable labels for overage/quota formatting */
+interface OverageLabels {
+    /** Singular unit fallback (default: "unit") */
+    unit: string;
+    /** Plural units fallback (default: "units") */
+    units: string;
+    /** "Included" label */
+    included: string;
+    /** "after that" separator */
+    afterThat: string;
+    /** "After included:" prefix when no included count */
+    afterIncluded: string;
+}
 /**
  * Format overage rate for display. When unitSize > 1: "$1.00/1,000 units"; else "$1.00/unit".
- * Returns null if overageCents is missing or negative.
+ * Pass `labels` for i18n support.
  */
-declare function formatOverageRate(overageCents: number | undefined, unitSize: number | undefined, currency: string): string | null;
+declare function formatOverageRate(overageCents: number | undefined, unitSize: number | undefined, currency: string, labels?: Partial<OverageLabels>): string | null;
 /**
  * Format overage rate with optional unit label for comparison/preview UIs.
- * e.g. formatOverageRateWithLabel(50, 1000, "video") -> "$0.50/1,000 videos"
- *      formatOverageRateWithLabel(46, 1, "video") -> "$0.46/video"
- * When unitLabel is omitted, falls back to formatOverageRate behavior.
+ * e.g. formatOverageRateWithLabel(50, 1000, "video", "usd") -> "$0.50/1,000 videos"
+ * Pass `labels` for i18n support. Pass `pluralUnitLabel` to avoid English "s" pluralization.
  */
-declare function formatOverageRateWithLabel(overageCents: number | undefined, unitSize: number | undefined, unitLabel: string | undefined, currency: string): string | null;
+declare function formatOverageRateWithLabel(overageCents: number | undefined, unitSize: number | undefined, unitLabel: string | undefined, currency: string, pluralUnitLabel?: string, labels?: Partial<OverageLabels>): string | null;
 /**
  * Get singular unit label from item name or slug (e.g. "Videos" -> "video", "reels" -> "reel").
  * Used for quota display in comparison and preview.
+ * Pass `fallback` for i18n unit fallback (default: "unit").
  */
-declare function getQuotaUnitLabelFromName(nameOrSlug: string): string;
+declare function getQuotaUnitLabelFromName(nameOrSlug: string, fallback?: string): string;
 /**
  * Format quota "included + overage" for display.
- * When unitSize >= 2: "Included: 1,000, after that $1.00/1,000 emails".
- * Otherwise: "Included: 5, after that $0.30/image".
+ * Pass `labels` and `pluralUnitLabel` for i18n support.
  */
-declare function formatQuotaIncludedOverage(included: number | undefined, overageCents: number | undefined, unitLabel: string, currency: string, unitSize?: number): string;
+declare function formatQuotaIncludedOverage(included: number | undefined, overageCents: number | undefined, unitLabel: string, currency: string, unitSize?: number, pluralUnitLabel?: string, labels?: Partial<OverageLabels>): string;
 
 type QuotaDisplayValue = {
     included: number;
@@ -1208,10 +1422,29 @@ interface FormatQuotaWithPriceOptions {
     currencySymbol?: string;
     /** Stripe currency code (e.g. 'usd', 'inr'). Used to resolve symbol when currencySymbol is not set. */
     currency?: string;
+    /**
+     * i18n labels for quota display. When provided, used instead of hardcoded English.
+     * Callers in React components should pass translated strings from `t()`.
+     */
+    labels?: QuotaLabels;
+}
+/** Translatable labels for quota formatting */
+interface QuotaLabels {
+    /** e.g. "included" — appended after count */
+    included: string;
+    /** e.g. "then" — separator between included and price */
+    then: string;
 }
 /**
- * Format a quota display value as "X included, then $Y.YY / unit" (e.g. "10 included, then $10.00 / video").
- * Assumes overage is the per-unit price (in cents when overageInCents is true).
+ * Format a quota display value as "X included, then $Y.YY / unit".
+ * Pass `labels` for i18n support.
+ *
+ * @example
+ * formatQuotaWithPrice(value, 'videos', { currency: 'inr' })
+ * // → "1 included, then ₹1.00 / 1,000 videos"
+ *
+ * formatQuotaWithPrice(value, 'वीडियो', { currency: 'inr', labels: { included: 'शामिल', then: 'फिर' } })
+ * // → "1 शामिल, फिर ₹1.00 / 1,000 वीडियो"
  */
 declare function formatQuotaWithPrice(value: QuotaDisplayValue, unitName: string, options?: FormatQuotaWithPriceOptions): string;
 
@@ -1312,8 +1545,10 @@ interface InviteValidation {
     canInvite: boolean;
     /** Reason the invite is blocked, or null if allowed. */
     blockReason: InviteBlockReason;
-    /** Human-readable message for the block reason. */
-    blockMessage: string | null;
+    /** i18n key for the block message. Resolve with t(blockMessageKey, blockMessageValues). */
+    blockMessageKey: string | null;
+    /** Values for ICU interpolation in the block message. */
+    blockMessageValues: Record<string, string | number> | null;
 }
 /**
  * Validate whether a new member can be invited given current seat/user limits.
@@ -1341,41 +1576,6 @@ declare function validateInvite(opts: {
  */
 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";
 
-declare const countries: {
-    value: string;
-    flag: string;
-    text: string;
-    currencyCode: string;
-    currencyIcon: string;
-}[];
-
-declare const uniqueCurrencies: {
-    value: string;
-    text: string;
-    icon: any;
-}[];
-
-declare const languages: {
-    value: string;
-    label: string;
-    flag: string;
-}[];
-
-declare const timezones: {
-    value: string;
-    abbr: string;
-    offset: number;
-    isdst: boolean;
-    text: string;
-    utc: string[];
-}[];
-
-declare const formSchema: z.ZodObject<{
-    name: z.ZodString;
-    email: z.ZodString;
-}, z.core.$strip>;
-type formValuesType = z.infer<typeof formSchema>;
-
 interface BetaFormData {
     name?: string;
     email: string;
@@ -1385,12 +1585,546 @@ interface BetaFormResponse {
     message: string;
 }
 
+/**
+ * Type-safe translation keys for the BuildBase SDK.
+ * All user-facing strings are defined here.
+ */
+interface SDKMessages {
+    settings: {
+        titles: {
+            profile: string;
+            general: string;
+            users: string;
+            subscription: string;
+            usage: string;
+            features: string;
+            notifications: string;
+            danger: string;
+        };
+        sidebar: {
+            account: string;
+            workspace: string;
+            profile: string;
+            general: string;
+            users: string;
+            subscription: string;
+            usage: string;
+            features: string;
+            notifications: string;
+            danger: string;
+        };
+        common: {
+            refresh: string;
+            refreshing: string;
+            retry: string;
+            retrying: string;
+            save: string;
+            saving: string;
+            cancel: string;
+            delete: string;
+            dismiss: string;
+            loading: string;
+            success: string;
+            error: string;
+            refreshAction: string;
+            retryAction: string;
+        };
+    };
+    subscription: {
+        managePlan: string;
+        changePlan: string;
+        viewPricingPlans: string;
+        viewPlans: string;
+        upgradePlan: string;
+        subscribe: string;
+        currentPlan: string;
+        noSubscription: string;
+        choosePlan: string;
+        choosePlanDescription: string;
+        planUpdateAvailable: string;
+        updateSuccess: string;
+        updateFailed: string;
+        cancelTitle: string;
+        cancelConfirm: string;
+        cancelKeep: string;
+        cancelButton: string;
+        canceling: string;
+        cancelSuccess: string;
+        cancelNotCharged: string;
+        cancelResumeAnytime: string;
+        resumeTitle: string;
+        resumeConfirm: string;
+        resumeKeep: string;
+        resumeButton: string;
+        resuming: string;
+        resumeSuccess: string;
+        managePayment: string;
+        openingPortal: string;
+        viewAllPlans: string;
+        scheduledCancellation: string;
+        paymentPastDue: string;
+        paymentPastDueDescription: string;
+        subscriptionPaused: string;
+        subscriptionPausedDescription: string;
+        errorLoading: string;
+        errorLoadingDescription: string;
+        errorProcessing: string;
+        errorCanceling: string;
+        errorResuming: string;
+        invalidWorkspace: string;
+        billingInterval: {
+            monthly: string;
+            quarterly: string;
+            yearly: string;
+            perMonth: string;
+            perQuarter: string;
+            perYear: string;
+        };
+        seats: {
+            title: string;
+            members: string;
+            included: string;
+            billable: string;
+            perExtraSeat: string;
+            limit: string;
+            includedSeats: string;
+            maxSeats: string;
+            freeWithBase: string;
+            allIncluded: string;
+            extra: string;
+            unlimited: string;
+        };
+        items: {
+            features: string;
+            limits: string;
+            quotas: string;
+        };
+        checkout: {
+            upgrade: string;
+            downgrade: string;
+            switchTo: string;
+            select: string;
+        };
+        status: {
+            active: string;
+            canceling: string;
+            trial: string;
+            canceled: string;
+            pastDue: string;
+            paused: string;
+            deprecated: string;
+            unknown: string;
+        };
+        plan: string;
+        invoicesTab: string;
+        changePlanButton: string;
+        noPlanAssigned: string;
+        free: string;
+        perSeatDisplay: string;
+        estTotalDisplay: string;
+        nextBillingDisplay: string;
+        membersInWorkspace: string;
+        billingInCurrency: string;
+        savingsPercent: string;
+        switchToInterval: string;
+        seatPriceDisplay: string;
+        trialEnded: string;
+        trialEndsIn: string;
+        onTrial: string;
+        upgradeToKeepAccess: string;
+        viewInvoices: string;
+        cancelTrial: string;
+        dunningFinal: string;
+        dunningSuspended: string;
+        dunningRecovery: string;
+        dunningSuspendedDescription: string;
+        dunningRecoveryDescription: string;
+        cancelEndDescription: string;
+        cancelEndFallback: string;
+        resumeChargeDate: string;
+        resumeChargeFallback: string;
+        resumeContinue: string;
+        resumeCancelAnytime: string;
+        retainAccess: string;
+        retainAccessFallback: string;
+        noPlansAvailable: string;
+        noPlansAvailableHint: string;
+        startTrialDescription: string;
+        noSubscriptionDescription: string;
+        startFreeTrial: string;
+    };
+    users: {
+        title: string;
+        adminOnly: string;
+        inviteByEmail: string;
+        inviteButton: string;
+        inviting: string;
+        inviteSuccess: string;
+        emailRequired: string;
+        invalidEmail: string;
+        inviteFailed: string;
+        seatLimitReached: string;
+        memberLimitReached: string;
+        role: string;
+        you: string;
+        owner: string;
+        noMembers: string;
+        extraSeatCost: string;
+        unknownUser: string;
+        seats: string;
+        members: string;
+        included: string;
+        perExtraSeat: string;
+        maxMembers: string;
+        available: string;
+        noMemberLimit: string;
+        seatHeading: string;
+        limitReached: string;
+        memberCount: string;
+        subscriptionRequired: string;
+        seatLimitMessage: string;
+        settingsLimitMessage: string;
+        memberLimitMessage: string;
+        selectRole: string;
+        inviteAs: string;
+    };
+    invoices: {
+        title: string;
+        description: string;
+        pay: string;
+        view: string;
+        viewDetails: string;
+        download: string;
+        errorLoading: string;
+        noInvoices: string;
+        noInvoicesWithSub: string;
+        paidAmount: string;
+        na: string;
+        status: {
+            draft: string;
+            open: string;
+            paid: string;
+            uncollectible: string;
+            void: string;
+        };
+    };
+    usage: {
+        title: string;
+        description: string;
+        totalResources: string;
+        overallUsage: string;
+        inOverage: string;
+        estOverageCost: string;
+        overageDetected: string;
+        overageDescription: string;
+        overageUnits: string;
+        rate: string;
+        billableBlocks: string;
+        estimatedCharge: string;
+        noData: string;
+        noDataHint: string;
+        used: string;
+        remaining: string;
+        overLimit: string;
+        percentUsed: string;
+        availableRemaining: string;
+        overLimitCount: string;
+        overageWarning: string;
+        fullyUsed: string;
+        renewingSoon: string;
+        almostFull: string;
+        overage: string;
+        errorLoading: string;
+        perUnit: string;
+        perUnits: string;
+        rateDisplay: string;
+        resourcesExceeded: string;
+        estOverageCharges: string;
+        overageRateDisplay: string;
+        resetDateDisplay: string;
+        daysRemainingDisplay: string;
+    };
+    profile: {
+        email: string;
+        name: string;
+        language: string;
+        country: string;
+        currency: string;
+        timezone: string;
+        profileImage: string;
+        success: string;
+        nameMinLength: string;
+        save: string;
+        reset: string;
+    };
+    general: {
+        ownerOnly: string;
+        name: string;
+        namePlaceholder: string;
+        nameMinLength: string;
+        billingCurrency: string;
+        icon: string;
+        iconDescription: string;
+        imageUrl: string;
+        imageUrlPlaceholder: string;
+        imageUrlDescription: string;
+        previewLabel: string;
+        success: string;
+        chooseEmoji: string;
+        customImageUrl: string;
+        updateWorkspace: string;
+    };
+    features: {
+        title: string;
+        ownerOnly: string;
+        noFeatures: string;
+        enabled: string;
+        disabled: string;
+        enabling: string;
+        disabling: string;
+        featureSuccess: string;
+        updateSuccess: string;
+        actionStatus: string;
+    };
+    danger: {
+        title: string;
+        adminOnly: string;
+        deleteWorkspace: string;
+        deleteConfirm: string;
+        deleteWarning: string;
+        deleting: string;
+        deleteDescription: string;
+        deleteConfirmDescription: string;
+        failedToDelete: string;
+    };
+    notifications: {
+        title: string;
+        permissionDenied: string;
+        notSupported: string;
+        manageDescription: string;
+        blocked: string;
+        blockedDescription: string;
+        pushTitle: string;
+        pushEnabledDescription: string;
+        pushDisabledDescription: string;
+        enabling: string;
+        disabling: string;
+        enable: string;
+        disable: string;
+        toggleAction: string;
+        pushDescription: string;
+        deviceNote: string;
+        unblock: {
+            firefox: {
+                step1: string;
+                step2: string;
+                step3: string;
+                step4: string;
+            };
+            safari: {
+                step1: string;
+                step2: string;
+                step3: string;
+                step4: string;
+            };
+            edge: {
+                step1: string;
+                step2: string;
+                step3: string;
+                step4: string;
+            };
+            chrome: {
+                step1: string;
+                step2: string;
+                step3: string;
+                step4: string;
+            };
+        };
+    };
+    quota: {
+        includedOnly: string;
+        includedWithOverage: string;
+        unitFallback: string;
+    };
+    pricing: {
+        title: string;
+        description: string;
+        currency: string;
+        billingIn: string;
+        noPlansCurrency: string;
+        noPlansCurrencyHint: string;
+        noPlans: string;
+        free: string;
+        included: string;
+        save: string;
+        current: string;
+        processing: string;
+        unavailable: string;
+        selectCurrency: string;
+        billingInterval: string;
+    };
+    beta: {
+        nameLabel: string;
+        emailLabel: string;
+        submitText: string;
+        submittingText: string;
+        errorMessage: string;
+        tryAgain: string;
+        privacyConsent: string;
+        privacyPolicy: string;
+        and: string;
+        termsOfService: string;
+    };
+    workspace: {
+        switchTitle: string;
+        switchDescription: string;
+        notLoggedIn: string;
+        availableWorkspaces: string;
+        loadingWorkspaces: string;
+        searchPlaceholder: string;
+        noWorkspacesFound: string;
+        noWorkspacesAvailable: string;
+        switchTo: string;
+        membersCount: string;
+        createNew: string;
+        createTitle: string;
+        createDescription: string;
+        workspaceName: string;
+        workspaceNamePlaceholder: string;
+        workspaceNameMinLength: string;
+        workspaceIcon: string;
+        iconDescription: string;
+        chooseEmoji: string;
+        customImageUrl: string;
+        imageUrl: string;
+        imageUrlPlaceholder: string;
+        imageUrlDescription: string;
+        invalidUrl: string;
+        creating: string;
+        createWorkspace: string;
+    };
+    dropdowns: {
+        search: string;
+        chooseOption: string;
+        chooseCountry: string;
+        searchCountry: string;
+        chooseLanguage: string;
+        searchLanguage: string;
+        chooseCurrency: string;
+        searchCurrency: string;
+        chooseTimezone: string;
+        searchTimezone: string;
+    };
+    push: {
+        failedToSubscribe: string;
+        failedToUnsubscribe: string;
+    };
+    errors: {
+        networkError: string;
+        unauthorized: string;
+        notFound: string;
+        generic: string;
+        fetchPlans: string;
+        fetchPlanGroup: string;
+        fetchPlanGroupVersion: string;
+        fetchPlanGroupVersions: string;
+        fetchSubscription: string;
+        createCheckout: string;
+        updateSubscription: string;
+        fetchInvoices: string;
+        fetchInvoice: string;
+        openBillingPortal: string;
+        cancelSubscription: string;
+        resumeSubscription: string;
+        recordUsage: string;
+        fetchQuotaUsage: string;
+        fetchAllQuotaUsage: string;
+        fetchUsageLogs: string;
+    };
+}
+/** Supported locale codes */
+type SDKLocale = 'en' | 'es' | 'fr' | 'de' | 'ja' | 'zh' | 'hi' | 'ar';
+/**
+ * Generates a union of all valid dot-separated key paths from SDKMessages.
+ * Supports up to 3 levels of nesting (covers all current keys).
+ * Used to make `t()` calls compile-time safe with autocomplete.
+ *
+ * @example
+ * TranslationKey → "settings.titles.profile" | "settings.common.refresh" | ...
+ */
+type Level1 = keyof SDKMessages & string;
+type Level2 = {
+    [K1 in Level1]: SDKMessages[K1] extends Record<string, unknown> ? `${K1}.${keyof SDKMessages[K1] & string}` : never;
+}[Level1];
+type Level3 = {
+    [K1 in Level1]: SDKMessages[K1] extends Record<string, unknown> ? {
+        [K2 in keyof SDKMessages[K1] & string]: SDKMessages[K1][K2] extends Record<string, unknown> ? `${K1}.${K2}.${keyof SDKMessages[K1][K2] & string}` : never;
+    }[keyof SDKMessages[K1] & string] : never;
+}[Level1];
+type Level4 = {
+    [K1 in Level1]: SDKMessages[K1] extends Record<string, unknown> ? {
+        [K2 in keyof SDKMessages[K1] & string]: SDKMessages[K1][K2] extends Record<string, unknown> ? {
+            [K3 in keyof SDKMessages[K1][K2] & string]: SDKMessages[K1][K2][K3] extends Record<string, unknown> ? `${K1}.${K2}.${K3}.${keyof SDKMessages[K1][K2][K3] & string}` : never;
+        }[keyof SDKMessages[K1][K2] & string] : never;
+    }[keyof SDKMessages[K1] & string] : never;
+}[Level1];
+/** Union of all valid translation key paths (e.g. "settings.titles.profile") */
+type TranslationKey = Level2 | Level3 | Level4;
+
+/** Values that can be interpolated into ICU messages */
+type TranslationValues = Record<string, string | number | boolean>;
+/** All supported locale codes */
+declare const SUPPORTED_LOCALES: SDKLocale[];
+/**
+ * Access SDK translations. Returns a type-safe `t()` function for nested key
+ * lookup with optional ICU MessageFormat interpolation.
+ *
+ * @example
+ * ```tsx
+ * const { t } = useTranslation();
+ *
+ * // Simple lookup — autocomplete and compile-time typo checking
+ * t('settings.common.refresh')  // → 'Refresh'
+ *
+ * // ICU interpolation with placeholders
+ * t('usage.estOverageCharges', { amount: '$12.50' })
+ * // → 'Estimated overage charges this period: $12.50'
+ *
+ * // ICU plural rules (handles Arabic's 6 forms, etc.)
+ * t('users.memberCount', { count: 3 })
+ * // → '3 members'
+ * ```
+ */
+declare function useTranslation(): {
+    t: (key: TranslationKey, values?: TranslationValues) => string;
+    locale: SDKLocale;
+    formattingLocale: string;
+    dir: "rtl" | "ltr";
+    fmtNum: (n: number) => string;
+    fmtCents: (cents: number, currency: string) => string;
+    messages: SDKMessages;
+};
+
 interface SaaSOSProviderProps extends IOsState {
     children: react__default.ReactNode;
+    /** SDK UI language. Defaults to 'en'. Supported: en, es, fr, de, ja, zh, hi, ar */
+    locale?: SDKLocale;
 }
 declare const SaaSOSProvider: react__default.FC<SaaSOSProviderProps>;
 
-type WorkspaceSettingsSection = 'profile' | 'general' | 'users' | 'subscription' | 'usage' | 'features' | 'notifications' | 'danger';
+declare const SettingsScreen: {
+    readonly Profile: "profile";
+    readonly General: "general";
+    readonly Users: "users";
+    readonly Subscription: "subscription";
+    readonly Usage: "usage";
+    readonly Features: "features";
+    readonly Notifications: "notifications";
+    readonly Danger: "danger";
+};
+type WorkspaceSettingsSection = (typeof SettingsScreen)[keyof typeof SettingsScreen];
+/** Set of all valid section values — used for runtime validation */
+declare const SETTINGS_SCREENS: Set<WorkspaceSettingsSection>;
 
 declare function useSaaSAuth(): {
     signIn: () => Promise<void>;
@@ -3039,8 +3773,10 @@ interface SeatStatus {
     canInvite: boolean;
     /** Reason the invite is blocked, or null if allowed. */
     inviteBlockReason: InviteBlockReason;
-    /** Human-readable message for why invite is blocked. */
-    inviteBlockMessage: string | null;
+    /** i18n key for the block message. Resolve with t(key, values). */
+    inviteBlockMessageKey: string | null;
+    /** Values for ICU interpolation in the block message. */
+    inviteBlockMessageValues: Record<string, string | number> | null;
 }
 /**
  * Hook that computes seat status from subscription context and workspace data.
@@ -3071,24 +3807,13 @@ declare function WorkspaceSwitcher(props: {
     trigger: (isLoading: boolean, currentWorkspace: IWorkspace | null) => ReactNode;
 }): react_jsx_runtime.JSX.Element;
 
-type Language = 'en' | 'es' | 'fr' | 'de' | 'zh' | 'ja' | 'ko';
-interface FormText {
-    nameLabel: string;
-    emailLabel: string;
-    submitText: string;
-    submittingText: string;
-    errorMessage: string;
-}
 interface BetaFormProps {
     onSuccess?: () => void;
     onError?: (error: string) => void;
     className?: string;
     fieldClassName?: string;
-    language?: Language;
-    customTexts?: Partial<FormText>;
     autoFocus?: boolean;
     showSuccessMessage?: boolean;
-    successMessageDuration?: number;
     hideLogo?: boolean;
     hideTitles?: boolean;
 }
@@ -3176,5 +3901,5 @@ declare const PushNotificationProvider: react__default.FC<PushNotificationProvid
  */
 declare function usePushNotifications(): PushNotificationContextValue;
 
-export { ApiVersion, AuthApi, AuthStatus, BaseApi, BetaForm, CURRENCY_DISPLAY, CURRENCY_FLAG, EventEmitter, PLAN_CURRENCY_CODES, PLAN_CURRENCY_OPTIONS, PUSH_SERVICE_WORKER_SCRIPT, PricingPage, PushApi, 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, formSchema as betaFormSchema, calculateBillableSeats, calculateSeatOverageCents, calculateTotalSubscriptionCents, countries, uniqueCurrencies as currencies, eventEmitter, formatCents, formatOverageRate, formatOverageRateWithLabel, formatQuotaIncludedOverage, formatQuotaWithPrice, getAvailableCurrenciesFromPlans, getBasePriceCents, getBillingIntervalAndCurrencyFromPriceId, getCurrencyFlag, getCurrencySymbol, getDisplayCurrency, getPerSeatPriceCents, getPricingVariant, getQuotaDisplayValue, getQuotaDisplayWithVariant, getQuotaOverageCents, getQuotaUnitLabelFromName, getSeatPricing, getStripePriceIdForInterval, invalidateQuotaUsage, invalidateSubscription, languages, resolveMaxUsers, timezones, 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, validateInvite };
-export type { BetaFormData, BetaFormResponse, formValuesType as BetaFormValues, BillingInterval, CheckoutResult, EventData, EventType, FormatQuotaWithPriceOptions, IAllQuotaUsageResponse, IBaseApiConfig, IBasePricing, IBetaConfig, ICheckoutSessionRequest, ICheckoutSessionResponse, 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, OnWorkspaceChangeParams, PlanVersionWithPricingVariants, PricingPageDetails, PricingPageProps, QuotaDisplayValue, QuotaDisplayWithOverage, QuotaUsageContextValue, SaaSOSProviderProps, SeatStatus, SubscriptionContextValue, TrialStatus, UserCreatedEventData, UserUpdatedEventData, WorkspaceChangedEventData, WorkspaceCreatedEventData, WorkspaceDeletedEventData, WorkspaceUpdatedEventData, WorkspaceUserAddedEventData, WorkspaceUserRemovedEventData, WorkspaceUserRoleChangedEventData };
+export { ApiVersion, AuthApi, AuthStatus, BB_PARAM, BaseApi, BetaForm, BillingIntervals, CURRENCY_DISPLAY, CURRENCY_FLAG, DunningState, EventEmitter, InvoiceStatuses, PLAN_CURRENCY_CODES, PLAN_CURRENCY_OPTIONS, PUSH_SERVICE_WORKER_SCRIPT, PricingPage, PushApi, PushNotificationProvider, QuotaUsageContextProvider, SDKEvent, SETTINGS_SCREENS, SUPPORTED_LOCALES, SaaSOSProvider, SettingsApi, SettingsScreen, SubscriptionContextProvider, SubscriptionItemType, SubscriptionStatus, UserApi, WhenAuthenticated, WhenNoSubscription, WhenNotTrialing, WhenQuotaAvailable, WhenQuotaExhausted, WhenQuotaOverage, WhenQuotaThreshold, WhenRoles, WhenSubscription, WhenSubscriptionToPlans, WhenTrialEnding, WhenTrialing, WhenUnauthenticated, WhenUserFeatureDisabled, WhenUserFeatureEnabled, WhenWorkspaceFeatureDisabled, WhenWorkspaceFeatureEnabled, WhenWorkspaceRoles, WorkspaceApi, WorkspaceSwitcher, calculateBillableSeats, calculateSeatOverageCents, calculateTotalSubscriptionCents, cleanBBParams, createBBUrl, createCheckoutRedirectUrls, eventEmitter, formatCents, formatOverageRate, formatOverageRateWithLabel, formatQuotaIncludedOverage, formatQuotaWithPrice, getAvailableCurrenciesFromPlans, getBasePriceCents, getBillingIntervalAndCurrencyFromPriceId, getCurrencyFlag, getCurrencySymbol, getDisplayCurrency, getPerSeatPriceCents, getPricingVariant, getQuotaDisplayValue, getQuotaDisplayWithVariant, getQuotaOverageCents, getQuotaUnitLabelFromName, getSeatPricing, getStripePriceIdForInterval, invalidateQuotaUsage, invalidateSubscription, readBBParams, resolveMaxUsers, safeRedirect, useAllQuotaUsage, useBillingPortal, useCancelSubscription, useCreateCheckoutSession, useInvoice, useInvoices, 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, 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, OnWorkspaceChangeParams, PlanVersionWithPricingVariants, PricingPageDetails, PricingPageProps, QuotaDisplayValue, QuotaDisplayWithOverage, QuotaUsageContextValue, SDKLocale, SDKMessages, SaaSOSProviderProps, SeatStatus, SubscriptionContextValue, SubscriptionStatusType, TrialStatus, UserCreatedEventData, UserUpdatedEventData, WorkspaceChangedEventData, WorkspaceCreatedEventData, WorkspaceDeletedEventData, WorkspaceSettingsSection, WorkspaceUpdatedEventData, WorkspaceUserAddedEventData, WorkspaceUserRemovedEventData, WorkspaceUserRoleChangedEventData };