@bpinternal/billing-ui 0.0.1

package/dist/index.d.ts

@@ -0,0 +1,892 @@
+import { Appearance } from '@stripe/stripe-js';
+import { billing } from '@botpress/client';
+import { ButtonHTMLAttributes } from 'react';
+import { ClassValue } from 'clsx';
+import { Client } from '@botpress/client';
+import { CSSProperties } from 'react';
+import { InputHTMLAttributes } from 'react';
+import { JSX } from 'react/jsx-runtime';
+import { QueryClient } from '@tanstack/react-query';
+import { ReactElement } from 'react';
+import { ReactNode } from 'react';
+import { ReactPortal } from 'react';
+import { SelectHTMLAttributes } from 'react';
+import { Stripe } from '@stripe/stripe-js';
+import { StripeCardElementOptions } from '@stripe/stripe-js';
+import { SVGProps } from 'react';
+import { UseMutationResult } from '@tanstack/react-query';
+import { UseQueryResult } from '@tanstack/react-query';
+
+export declare function addDays(iso: string, days: number): string;
+
+export declare type Addon = Awaited<ReturnType<BillingClient['listAddons']>>[number];
+
+/** Strip Smaug's "Add-on - " name prefix. */
+export declare function addonDisplayName(name: string): string;
+
+/**
+ * "Now → New" resource totals once the selected add-on quantities are applied.
+ * new = plan base feature + Σ (quantity × add-on increment) across add-ons that grant it.
+ * Only returns rows that actually change, so the preview stays focused.
+ */
+export declare function addonLimitsPreview(plan: Plan, addons: Addon[] | undefined, quantities: Record<string, number>): LimitPreviewRow[];
+
+/**
+ * Add-on price for a given plan. Smaug keys add-on prices by plan id
+ * (e.g. { plus: { amount: 65 }, team: { amount: 50 } }); fall back to kind, then
+ * to an interval key for environments that price add-ons globally.
+ *
+ * Deliberately does NOT fall back to "any price with a matching interval" — that
+ * would borrow another plan's price for a plan that isn't sold add-ons at all
+ * (e.g. community), making them look purchasable when they aren't. A plan with no
+ * id/kind/interval-keyed price returns null → no add-ons offered.
+ */
+export declare function addonPrice(addon: Addon, plan: Plan, interval: BillingInterval): {
+    amount: number;
+    currency: string;
+} | null;
+
+/**
+ * Clickable summary of active add-ons (current quantities from the live
+ * subscription). Acts as a preview button that opens add-on management.
+ */
+export declare const AddonsSummaryCard: ({ onManage, className }: AddonsSummaryCardProps) => JSX.Element;
+
+export declare type AddonsSummaryCardProps = {
+    /** Opens the manage-add-ons dialog. */
+    onManage: () => void;
+    className?: string;
+};
+
+export declare const Badge: ({ variant, children, className }: BadgeProps) => JSX.Element;
+
+export declare type BadgeProps = {
+    variant?: 'accent' | 'neutral' | 'success';
+    children: ReactNode;
+    className?: string;
+};
+
+export declare const BankIcon: ({ size, ...props }: IconProps) => JSX.Element;
+
+export declare type BillingAddress = {
+    lineOne: string;
+    lineTwo?: string;
+    city: string;
+    state?: string;
+    postalCode: string;
+    country: string;
+};
+
+export declare type BillingAnalytics = {
+    trackPaymentDetailsConfirmed?: (props: {
+        plan_name: string;
+        interval: BillingInterval;
+    }) => void;
+    trackPlanUpgradeInitiated?: (props: {
+        plan_name: string;
+        interval: BillingInterval;
+        current_plan_name?: string;
+    }) => void;
+    trackPlanUpgraded?: (props: {
+        plan_name: string;
+        interval: BillingInterval;
+        amount_paid: number;
+        next_cycle_amount: number;
+        previous_plan_name?: string;
+        previous_interval?: BillingInterval;
+    }) => void;
+    trackPlanDowngraded?: (props: {
+        plan_name: string;
+        interval: BillingInterval;
+        previous_plan_name?: string;
+    }) => void;
+    trackPlanDowngradeCancelled?: (props: {
+        plan_name: string;
+    }) => void;
+};
+
+export declare type BillingChangeEvent = {
+    type: 'subscription' | 'addons' | 'payment-method' | 'billing-address';
+};
+
+/**
+ * The billing engine surface this UI library talks to — literally the subset of
+ * `@botpress/client`'s `billing.Client` (Smaug v4) we call.
+ *
+ * `@botpress/client` is a type-only import (erased at runtime — no hard
+ * dependency): pass a real `billing.Client` instance straight in, or implement
+ * this interface over your own backend proxy (e.g. tRPC) — the shapes are the
+ * official wire shapes, the transport is yours.
+ */
+export declare type BillingClient = Pick<billing.Client, 'listPlans' | 'listAddons' | 'getSubscription' | 'previewSubscriptionUpdate' | 'setPlan' | 'setAddons' | 'getPaymentMethod' | 'createPaymentMethodIntent' | 'setPaymentMethod' | 'getBillingAddress' | 'setBillingAddress' | 'getCustomer' | 'setCustomer' | 'listInvoices' | 'getBillingReadonly' | 'getWorkspaceUsages'> & 
+/**
+* Per-bot usage breakdown is OPTIONAL: those methods live on the generic
+* `@botpress/client` (not the billing client), so a host that wants the per-bot
+* view passes a client object that also exposes them. Omit them and the
+* UsageDashboard hides the per-bot section. Still type-only — no runtime dep.
+*/
+Partial<Pick<Client, 'breakDownWorkspaceUsageByBot' | 'listBots'>>;
+
+declare type BillingContextValue = {
+    client: BillingClient;
+    queryClient: QueryClient;
+    /** Workspace scope used to namespace query keys (workspaceId or 'default'). */
+    scope: string;
+    stripePromise: Promise<Stripe | null>;
+    email?: string;
+    locale: string;
+    isDark: boolean;
+    toast: (toast: BillingToast) => void;
+    analytics: BillingAnalytics;
+    featureLabels?: Record<string, (quantity: number) => string>;
+    isOutdatedBilling: boolean;
+    manageBillingUrl?: string;
+    /** Background poll interval (ms) for queries; `false` when disabled (≤ 0). */
+    refetchInterval: number | false;
+    /** Re-fetch all billing data (plans, subscription, add-ons, …). Awaitable. */
+    refresh: () => Promise<void>;
+    /** Internal: notify the host that billing changed. Called by the mutation hooks. */
+    notifyBillingChange: (event: BillingChangeEvent) => void;
+};
+
+export declare type BillingInterval = 'month' | 'year';
+
+export declare const billingKeys: {
+    /** Everything for one workspace — use to invalidate/clear the whole scope. */
+    root: (scope: string) => readonly ["bpb", string];
+    plans: (scope: string) => readonly ["bpb", string, "plans"];
+    addons: (scope: string) => readonly ["bpb", string, "addons"];
+    subscription: (scope: string) => readonly ["bpb", string, "subscription"];
+    preview: (scope: string, update: SubscriptionUpdate) => readonly ["bpb", string, "preview", SubscriptionUpdate];
+    paymentMethod: (scope: string) => readonly ["bpb", string, "payment-method"];
+    billingAddress: (scope: string) => readonly ["bpb", string, "billing-address"];
+    customer: (scope: string) => readonly ["bpb", string, "customer"];
+    invoices: (scope: string) => readonly ["bpb", string, "invoices"];
+    readonly: (scope: string) => readonly ["bpb", string, "billing-readonly"];
+    usages: (scope: string, period: string) => readonly ["bpb", string, "usages", string];
+    bots: (scope: string) => readonly ["bpb", string, "bots"];
+    usageByBot: (scope: string, type: string, period: string) => readonly ["bpb", string, "usage-by-bot", string, string];
+};
+
+export declare const BillingProvider: ({ client, stripePublishableKey, email, locale, theme, onToast, analytics, featureLabels, billingVersion, workspaceId, persist, manageBillingUrl, onBillingChange, refreshInterval, children, }: BillingProviderProps) => JSX.Element;
+
+export declare type BillingProviderProps = {
+    /** Billing engine client — `@botpress/client`'s `billing.Client` or any compatible adapter */
+    client: BillingClient;
+    /** Stripe publishable key (pk_…). The only Stripe key the frontend ever sees. */
+    stripePublishableKey: string;
+    /** Workspace owner email shown in the checkout contact section */
+    email?: string;
+    locale?: string;
+    theme?: BillingTheme;
+    onToast?: (toast: BillingToast) => void;
+    analytics?: BillingAnalytics;
+    /** Override the human label shown for a plan feature key (e.g. bot_count) */
+    featureLabels?: Record<string, (quantity: number) => string>;
+    /**
+     * Workspace billing version (from the generic client's `getWorkspace().billingVersion`).
+     * Smaug only serves v4 — any other value makes the dialogs render a
+     * "manage billing in Dashboard" gate instead of the self-serve flow.
+     * Omit if the host app gates on the version itself.
+     */
+    billingVersion?: string;
+    /**
+     * Workspace id. Used to namespace the query cache so one workspace's billing
+     * data never leaks into another's, and to scope persisted cache (see `persist`).
+     * Strongly recommended when a host can switch workspaces. Defaults to 'default'.
+     */
+    workspaceId?: string;
+    /**
+     * Persist the billing cache to localStorage so it survives reloads (instant
+     * render, then a background refresh). On by default. Only the current
+     * workspace's scope is stored, keyed by `workspaceId`. Set false to opt out.
+     */
+    persist?: boolean;
+    /** Where the gate sends the user, e.g. https://app.botpress.cloud/workspaces/{id}/billing */
+    manageBillingUrl?: string;
+    /**
+     * Fired after any billing change the library commits (subscribe, plan change,
+     * add-on update). The library already refreshes its own queries; use this to
+     * refresh billing UI the host renders OUTSIDE this provider (e.g. a plan badge
+     * elsewhere in the app). The argument names what changed.
+     */
+    onBillingChange?: (event: BillingChangeEvent) => void;
+    /**
+     * How often (ms) to poll billing data (subscription, usage, …) in the background.
+     * Defaults to 30_000. Set to 0 (or any value ≤ 0) to disable background refresh.
+     */
+    refreshInterval?: number;
+    children: ReactNode;
+};
+
+export declare type BillingTheme = 'light' | 'dark' | 'system';
+
+export declare type BillingToast = {
+    type: 'success' | 'error';
+    message: string;
+};
+
+export declare const BoltIcon: ({ size, ...props }: IconProps) => JSX.Element;
+
+/** A per-bot usage row enriched with the bot's display name. */
+export declare type BotUsageRow = {
+    botId: string;
+    name: string;
+    value: number;
+};
+
+export declare const Button: ({ variant, size, block, loading, className, disabled, children, type, ...props }: ButtonProps) => JSX.Element;
+
+export declare type ButtonProps = ButtonHTMLAttributes<HTMLButtonElement> & {
+    variant?: 'primary' | 'accent' | 'outline' | 'ghost';
+    size?: 'sm' | 'md' | 'lg';
+    block?: boolean;
+    loading?: boolean;
+    children?: ReactNode;
+};
+
+export declare const CalendarIcon: ({ size, ...props }: IconProps) => JSX.Element;
+
+/** Minimal card-brand badge (saved-card row). Stripe's own UI shows real brand art. */
+export declare const CardBrandBadge: ({ brand }: {
+    brand: string;
+}) => JSX.Element;
+
+export declare const CardIcon: ({ size, ...props }: IconProps) => JSX.Element;
+
+export declare const ChartIcon: ({ size, ...props }: IconProps) => JSX.Element;
+
+export declare const CheckIcon: ({ size, ...props }: IconProps) => JSX.Element;
+
+/**
+ * "Configure your plan" — checkout (plan interval, payment method via Stripe
+ * CardElement, billing address, business VAT, proration preview + subscribe).
+ *
+ * A Stripe SetupIntent is created every time the dialog opens and the whole
+ * body mounts inside one <Elements> tree so CardElement, AddressElement and
+ * the subscribe button share the same Stripe context.
+ */
+export declare const CheckoutDialog: ({ open, onOpenChange, planId, interval, onBack, onSuccess }: CheckoutDialogProps) => JSX.Element;
+
+export declare type CheckoutDialogProps = {
+    open: boolean;
+    onOpenChange: (open: boolean) => void;
+    planId: string;
+    /** Initial billing interval — the user can still switch inside the dialog */
+    interval: BillingInterval;
+    /** Back to the plan picker (renders the ‹ chevron when provided) */
+    onBack?: () => void;
+    onSuccess?: () => void;
+};
+
+export declare const ChevronDownIcon: ({ size, ...props }: IconProps) => JSX.Element;
+
+export declare const ChevronLeftIcon: ({ size, ...props }: IconProps) => JSX.Element;
+
+export declare const ChevronRightIcon: ({ size, ...props }: IconProps) => JSX.Element;
+
+export declare const CloseIcon: ({ size, ...props }: IconProps) => JSX.Element;
+
+export declare function cn(...inputs: ClassValue[]): string;
+
+/**
+ * Per-pack conversations pricing for a plan, e.g. { packSize: 100, amount: 65 }
+ * → "+$65 per 100 conversations". Returns null when the plan has no overage add-on
+ * (e.g. Free) or the add-on isn't priced for it.
+ */
+export declare function conversationPackPrice(addons: Addon[] | undefined, plan: Plan, interval: BillingInterval): {
+    packSize: number;
+    amount: number;
+    currency: string;
+} | null;
+
+/** The add-on that sells extra conversations (keyed by its conversation_sessions increment). */
+export declare function conversationsAddon(addons: Addon[] | undefined): Addon | null;
+
+/** Currency code → its symbol ("usd" → "$", "eur" → "€"); falls back to the uppercased code. */
+export declare function currencySymbol(currency: string): string;
+
+export declare type Customer = Awaited<ReturnType<BillingClient['getCustomer']>>;
+
+/**
+ * Plain-language explanations of what each plan feature means, keyed by the exact
+ * marketing label above. Shown as a hover tooltip in the pricing table. Override
+ * per-app via UpgradePlanDialog's `featureDescriptions` prop.
+ */
+export declare const DEFAULT_FEATURE_DESCRIPTIONS: Record<string, string>;
+
+/**
+ * Human labels for Smaug plan feature keys. Overridable per-key via the
+ * BillingProvider `featureLabels` prop.
+ */
+export declare const DEFAULT_FEATURE_LABELS: Record<string, (quantity: number) => string>;
+
+/**
+ * Curated marketing feature lists per plan kind — what the pricing table says,
+ * mirroring Desk's billing-features. Quota numbers stay out of this list; the
+ * conversations volume is rendered as the card's headline metric instead.
+ * Override per-app via UpgradePlanDialog's `planFeatures` prop.
+ */
+export declare const DEFAULT_PLAN_FEATURES: Record<PlanKind, string[]>;
+
+export declare const Dialog: ({ open, onOpenChange, size, children, className, showClose, ...aria }: DialogProps) => ReactPortal | null;
+
+export declare type DialogProps = {
+    open: boolean;
+    onOpenChange: (open: boolean) => void;
+    /** sm = confirm, md = form, xl = full checkout / plan picker */
+    size?: 'sm' | 'md' | 'xl';
+    'aria-label': string;
+    children: ReactNode;
+    className?: string;
+    showClose?: boolean;
+};
+
+export declare const DownloadIcon: ({ size, ...props }: IconProps) => JSX.Element;
+
+export declare const ENTERPRISE_CONTACT_URL = "https://botpress.com/contact-us/managed-plan";
+
+export declare type Entitlement = {
+    key: string;
+    label: string;
+    unit: 'count' | 'bytes';
+    /** Plan base allowance. */
+    base: number;
+    /** Extra granted by active add-ons (Σ quantity × increment). */
+    added: number;
+    /** base + added. */
+    total: number;
+};
+
+export declare const ExternalLinkIcon: ({ size, ...props }: IconProps) => JSX.Element;
+
+/** Description for a feature label — exact map first, then a keyword fallback for templated quota labels. */
+export declare function featureDescription(label: string, overrides?: Record<string, string>): string | undefined;
+
+export declare function featureLabel(key: string, quantity: number, overrides?: Record<string, (quantity: number) => string>): string;
+
+/** Human-readable bytes — "10 GB", "1.5 GB", "500 MB". */
+export declare function formatBytes(bytes: number): string;
+
+export declare function formatCurrency(amount: number, currency?: string, decimal?: number): string;
+
+export declare function formatDate(iso: string, locale?: string): string;
+
+export declare function formatQuantity(n: number): string;
+
+export declare function formatUsage(value: number, unit: UsageUnit): string;
+
+export declare function getCardElementStyle(isDark: boolean): StripeCardElementOptions['style'];
+
+export declare function getStripeAppearance(isDark: boolean): Appearance;
+
+export declare function getStripePromise(publishableKey: string): Promise<Stripe | null>;
+
+export declare const GlobeIcon: ({ size, ...props }: IconProps) => JSX.Element;
+
+/**
+ * Pick a feature glyph from its marketing label (ChatGPT-style top-feature icons).
+ * Keyword-matched, with a generic sparkle fallback so every line still gets an icon.
+ */
+export declare function iconForFeature(label: string): (props: IconProps) => ReactElement;
+
+declare type IconProps = SVGProps<SVGSVGElement> & {
+    size?: number;
+};
+
+export declare const InfinityIcon: ({ size, ...props }: IconProps) => JSX.Element;
+
+/**
+ * A dotted-underlined term that reveals an explanatory tooltip on hover or
+ * keyboard focus. CSS-only positioning (centered above the term), so it carries
+ * no JS/positioning dependency.
+ */
+export declare const InfoTooltip: ({ label, children }: InfoTooltipProps) => JSX.Element;
+
+export declare type InfoTooltipProps = {
+    /** The term to annotate — gets a dotted underline + help cursor. */
+    label: ReactNode;
+    /** Tooltip body shown on hover/focus. */
+    children: ReactNode;
+};
+
+/** Floating-label input matching Stripe Elements' field look (grey fill, label inside). */
+export declare const Input: ({ label, className, id, ...props }: InputProps) => JSX.Element;
+
+export declare type InputProps = InputHTMLAttributes<HTMLInputElement> & {
+    label?: string;
+};
+
+export declare type Invoice = Awaited<ReturnType<BillingClient['listInvoices']>>['invoices'][number];
+
+/**
+ * Read-only billing history. Lists invoices newest-first with status, amount,
+ * period, and a PDF download when Stripe provides one.
+ */
+export declare const InvoicesDialog: ({ open, onOpenChange }: InvoicesDialogProps) => JSX.Element;
+
+export declare type InvoicesDialogProps = {
+    open: boolean;
+    onOpenChange: (open: boolean) => void;
+};
+
+export declare const LayersIcon: ({ size, ...props }: IconProps) => JSX.Element;
+
+export declare type LimitPreviewRow = {
+    key: string;
+    label: string;
+    unit: 'count' | 'bytes';
+    now: number;
+    next: number;
+};
+
+export declare const LockIcon: ({ size, ...props }: IconProps) => JSX.Element;
+
+/**
+ * Add-on management for the CURRENT subscription (Desk's manage-subscription
+ * parity): quantities seeded from the live subscription (scheduled `next`
+ * first), totals computed client-side, committed as absolute quantities via
+ * setAddons — 0 removes an add-on. No plan change involved.
+ */
+export declare const ManageAddonsDialog: ({ open, onOpenChange, onSuccess }: ManageAddonsDialogProps) => JSX.Element;
+
+export declare type ManageAddonsDialogProps = {
+    open: boolean;
+    onOpenChange: (open: boolean) => void;
+    onSuccess?: () => void;
+};
+
+export declare const MessageIcon: ({ size, ...props }: IconProps) => JSX.Element;
+
+export declare const MinusIcon: ({ size, ...props }: IconProps) => JSX.Element;
+
+/** Smaug reports ai_spend in nano-dollars (1e9 nano = $1) — same as the dashboard. */
+export declare const NANO_DOLLARS_PER_DOLLAR = 1000000000;
+
+/**
+ * Shown instead of the self-serve flow when the workspace isn't on billing v4
+ * (Smaug). Legacy versions (v1–v3) are managed in the Botpress Dashboard.
+ */
+export declare const OutdatedBillingGate: () => JSX.Element;
+
+export declare const PaintIcon: ({ size, ...props }: IconProps) => JSX.Element;
+
+export declare type PaymentMethod = NonNullable<Awaited<ReturnType<BillingClient['getPaymentMethod']>>['paymentMethod']>;
+
+export declare type PaymentMethodCard = NonNullable<PaymentMethod['card']>;
+
+/**
+ * Update the saved card and/or billing address. A fresh SetupIntent is created
+ * on open and the whole body mounts inside one <Elements> tree so the
+ * CardElement and AddressElement share Stripe context. Card is confirmed via
+ * confirmCardSetup (no address required), then persisted; address is saved
+ * independently — matching Desk's separation.
+ */
+export declare const PaymentMethodDialog: ({ open, onOpenChange, onSuccess }: PaymentMethodDialogProps) => JSX.Element;
+
+export declare type PaymentMethodDialogProps = {
+    open: boolean;
+    onOpenChange: (open: boolean) => void;
+    onSuccess?: () => void;
+};
+
+export declare type Plan = Awaited<ReturnType<BillingClient['listPlans']>>[number];
+
+export declare const PLAN_ORDER: PlanKind[];
+
+/**
+ * Full-width current-plan hero with per-tier color identity (accent rail + name,
+ * soft tinted surface). Surfaces the plan name, total monthly/annual cost
+ * (plan + add-ons), conversation allowance, the billing period and when it
+ * renews, plus a manage CTA. On legacy billing it deep-links to the Dashboard.
+ */
+export declare const PlanBanner: ({ onManage, className }: PlanBannerProps) => JSX.Element;
+
+export declare type PlanBannerProps = {
+    /** Opens the plan picker / checkout. */
+    onManage: () => void;
+    className?: string;
+};
+
+/** "Plan - Plus" → "Plus" (Smaug prefixes plan names) */
+export declare function planDisplayName(name: string): string;
+
+/**
+ * Current total entitlements per resource = plan base + active add-on packs.
+ * `quantities` maps add-on id → owned quantity (from the live subscription).
+ * Returns one row per known resource the plan or its add-ons provide, so a
+ * caller can render e.g. "250 + 300 conversations" (base + added).
+ */
+export declare function planEntitlements(plan: Plan | undefined, addons: Addon[] | undefined, quantities: Record<string, number>): Entitlement[];
+
+/**
+ * Canonical plan kinds. Smaug plan ids/names vary by environment, so plans are
+ * classified by name — same heuristic as the dashboard's getPlanNameFromId.
+ */
+export declare type PlanKind = 'community' | 'plus' | 'team' | 'enterprise' | 'managed';
+
+export declare function planKind(plan: Pick<Plan, 'name' | 'metadata'>): PlanKind;
+
+/**
+ * Clickable summary of the current plan — name, interval, price, conversation
+ * allowance. Acts as a preview button that opens the plan-management flow.
+ */
+export declare const PlanSummaryCard: ({ onManage, className }: PlanSummaryCardProps) => JSX.Element;
+
+export declare type PlanSummaryCardProps = {
+    /** Opens the plan picker / checkout. */
+    onManage: () => void;
+    className?: string;
+};
+
+/**
+ * Ultra-compact plan + conversations-usage summary for a dropdown/menu.
+ * Full-width (adapts to the menu), shows the plan name and a "N left"
+ * conversations bar with its reset date. Hidden on legacy billing.
+ */
+export declare const PlanUsageWidget: ({ onManage, period, variant, className, style }: PlanUsageWidgetProps) => JSX.Element | null;
+
+export declare type PlanUsageWidgetProps = {
+    /** Click handler — e.g. open the plan picker or navigate to billing. Renders a › affordance when set. */
+    onManage?: () => void;
+    /** Period (any datetime in the billing month); defaults to current month. */
+    period?: string;
+    /**
+     * Surface treatment:
+     * - 'card' (default) — its own filled, rounded surface.
+     * - 'plain' — transparent, no padding; inherits the host container's surface
+     *   (e.g. to blend into a sidebar). The host owns the background.
+     */
+    variant?: 'card' | 'plain';
+    className?: string;
+    /**
+     * Inline styles on the root. Handy for overriding the surface via the library's
+     * CSS variables, e.g. `style={{ ['--bpb-bg-input']: 'transparent' }}`.
+     */
+    style?: CSSProperties;
+};
+
+export declare const PlusIcon: ({ size, ...props }: IconProps) => JSX.Element;
+
+export declare type PreviewLineItem = SubscriptionPreview['costs']['immediate']['lineItems'][number];
+
+export declare type Price = NonNullable<Plan['prices']['month']>;
+
+export declare const PuzzleIcon: ({ size, ...props }: IconProps) => JSX.Element;
+
+declare type QueryOptions = {
+    enabled?: boolean;
+};
+
+export declare const ReceiptIcon: ({ size, ...props }: IconProps) => JSX.Element;
+
+export declare const SegmentedControl: <T extends string>({ options, value, onChange, className, ...aria }: SegmentedControlProps<T>) => JSX.Element;
+
+export declare type SegmentedControlOption<T extends string> = {
+    value: T;
+    label: string;
+    badge?: string;
+};
+
+export declare type SegmentedControlProps<T extends string> = {
+    options: SegmentedControlOption<T>[];
+    value: T;
+    onChange: (value: T) => void;
+    'aria-label': string;
+    className?: string;
+};
+
+export declare const Select: ({ label, className, children, ...props }: SelectProps) => JSX.Element;
+
+export declare type SelectProps = SelectHTMLAttributes<HTMLSelectElement> & {
+    label?: string;
+};
+
+declare type SetCustomerInput = {
+    name?: string;
+    address?: BillingAddress;
+    taxIds?: TaxId[];
+};
+
+declare type SetSubscriptionInput = {
+    planId: string;
+    interval: BillingInterval;
+    addons?: Record<string, number>;
+    couponCode?: string;
+};
+
+export declare const ShieldIcon: ({ size, ...props }: IconProps) => JSX.Element;
+
+export declare const Skeleton: ({ width, height, rounded, className }: SkeletonProps) => JSX.Element;
+
+export declare type SkeletonProps = {
+    width?: number | string;
+    height?: number | string;
+    rounded?: boolean;
+    className?: string;
+};
+
+export declare const SparkleIcon: ({ size, ...props }: IconProps) => JSX.Element;
+
+export declare const Stepper: ({ value, onChange, min, max, step, className, ...aria }: StepperProps) => JSX.Element;
+
+export declare type StepperProps = {
+    value: number;
+    onChange: (value: number) => void;
+    min?: number;
+    max?: number;
+    step?: number;
+    'aria-label': string;
+    className?: string;
+};
+
+export declare type Subscription = Awaited<ReturnType<BillingClient['getSubscription']>>;
+
+export declare type SubscriptionPreview = Awaited<ReturnType<BillingClient['previewSubscriptionUpdate']>>;
+
+export declare type SubscriptionStatus = Subscription['plan']['current']['status'];
+
+export declare type SubscriptionUpdate = {
+    plan: {
+        planId: string;
+        interval: BillingInterval;
+    };
+    /** Addon id → desired quantity. 0 removes the addon. */
+    addons?: Record<string, number>;
+    couponCode?: string;
+};
+
+export declare type TaxId = Customer['taxIds'][number];
+
+export declare function toStripeLocale(locale: string): string;
+
+export declare const UpgradePlanDialog: ({ open, onOpenChange, onSelectPlan, recommendedPlanId, defaultInterval, excludePlanIds, planFeatures, featureDescriptions, }: UpgradePlanDialogProps) => JSX.Element;
+
+export declare type UpgradePlanDialogProps = {
+    open: boolean;
+    onOpenChange: (open: boolean) => void;
+    /** Called when the user picks an upgrade — open the CheckoutDialog with these values. */
+    onSelectPlan: (planId: string, interval: BillingInterval) => void;
+    /** Plan kind (or exact id) to mark as Recommended. Desk recommends `team`. */
+    recommendedPlanId?: string;
+    defaultInterval?: BillingInterval;
+    /** Additional plan ids to hide. Enterprise + managed are always hidden. */
+    excludePlanIds?: string[];
+    /** Per-kind marketing feature strings; defaults to DEFAULT_PLAN_FEATURES (Desk copy). */
+    planFeatures?: Partial<Record<PlanKind, string[]>>;
+    /** Feature label → tooltip description; merged over DEFAULT_FEATURE_DESCRIPTIONS. */
+    featureDescriptions?: Record<string, string>;
+};
+
+/**
+ * The user-facing billing quotas surfaced in usage UI. getWorkspaceUsages also
+ * returns internal counters (bot count, incoming messages, collaborator count,
+ * saved/indexed file counts, …) that aren't billing concerns — keys not listed
+ * here are ignored. Order is the display priority.
+ */
+export declare const USAGE_METRICS: {
+    key: string;
+    label: string;
+    unit: UsageUnit;
+}[];
+
+/**
+ * A usage warning banner — visible only when a quota is past `threshold` (90%
+ * by default), on billing v4. Renders nothing otherwise (and on legacy billing),
+ * so it's safe to mount unconditionally on any page.
+ */
+export declare const UsageBanner: ({ position, threshold, onUpgrade, dismissible, ctaLabel, period, className, }: UsageBannerProps) => JSX.Element | null;
+
+export declare type UsageBannerProps = {
+    /**
+     * Mount behavior:
+     * - 'inline' (default) — sits in normal flow and pushes the page content down.
+     * - 'sticky-top' — sticks to the top of the scroll container.
+     * - 'fixed-top' / 'fixed-bottom' — pinned to the viewport (overlays content).
+     */
+    position?: 'inline' | 'sticky-top' | 'fixed-top' | 'fixed-bottom';
+    /** Consumption fraction that triggers the banner (0–1). Default 0.9 (90%). */
+    threshold?: number;
+    /**
+     * Primary CTA handler. If omitted, the banner opens its own plan picker +
+     * checkout so it works with zero host wiring.
+     */
+    onUpgrade?: () => void;
+    /** Show a dismiss (×) button. The banner reappears on remount. Default true. */
+    dismissible?: boolean;
+    /** CTA label. Default "Upgrade plan". */
+    ctaLabel?: string;
+    /** Period (any datetime in the billing month) to evaluate; defaults to current month. */
+    period?: string;
+    className?: string;
+};
+
+/** A client that can serve per-bot usage (both optional methods present). */
+export declare type UsageBreakdownClient = Required<Pick<Client, 'breakDownWorkspaceUsageByBot' | 'listBots'>>;
+
+/** One { botId, value } row from a per-bot usage breakdown. */
+export declare type UsageBreakdownEntry = Awaited<ReturnType<Client['breakDownWorkspaceUsageByBot']>>['data'][number];
+
+/**
+ * Read-only usage overview for the current billing month, grouped into
+ * Conversations / Storage / AI usage. Data comes from getWorkspaceUsages — the
+ * UI invents no numbers. A bare-minimum dashboard, not a deep analytics view.
+ */
+export declare const UsageDashboard: ({ period, showPeriodSelector, periodMonths, className, }: UsageDashboardProps) => JSX.Element;
+
+export declare type UsageDashboardProps = {
+    /** Any datetime within the billing month to report; defaults to the current month. */
+    period?: string;
+    /** Show a month dropdown to browse past billing periods. Default true. */
+    showPeriodSelector?: boolean;
+    /** How many recent months the period selector offers (incl. current). Default 12. */
+    periodMonths?: number;
+    className?: string;
+};
+
+export declare type UsageEntry = WorkspaceUsages[string];
+
+export declare type UsageItem = {
+    key: string;
+    label: string;
+    unit: UsageUnit;
+    used: number;
+    quota: number;
+    remaining: number;
+    /** Consumed percentage, 0–100. */
+    pct: number;
+};
+
+/** Resolve the user-facing usage metrics (with a real quota), highest-consumed first. */
+export declare function usageItems(quotas: WorkspaceUsages | undefined): UsageItem[];
+
+/**
+ * Wraps any element with a usage popover — a themed card showing the plan,
+ * reset date, and every user-facing quota with a mini bar. Reveals on
+ * hover/focus after `delay`. Renders the children plainly on legacy billing
+ * or when there's no usage to show (the popover just never opens).
+ */
+export declare const UsagePopover: ({ children, delay, placement, period, className }: UsagePopoverProps) => JSX.Element;
+
+export declare type UsagePopoverProps = {
+    /** The trigger — hovering/focusing it reveals the usage popover. */
+    children: ReactNode;
+    /** Delay in ms before the popover appears on hover/focus. Default 200. */
+    delay?: number;
+    /** Where the card opens relative to the trigger. Default 'top'. */
+    placement?: 'top' | 'bottom';
+    /** Period (any datetime in the billing month); defaults to current month. */
+    period?: string;
+    className?: string;
+};
+
+/**
+ * A compact circular usage indicator — the ring reflects the MOST-consumed
+ * metric across all quotas (conversations, AI spend, storage, …), colored by
+ * tier (blue ≤75%, amber 75–90%, red 90%+). Hovering reveals a UsagePopover
+ * listing every metric. Renders nothing on legacy billing / while loading.
+ */
+export declare const UsageRing: ({ size, thickness, showLabel, onClick, popoverDelay, period, className, ...aria }: UsageRingProps) => JSX.Element | null;
+
+export declare type UsageRingProps = {
+    /** Diameter in px. Default 20. */
+    size?: number;
+    /** Ring thickness in px. Default 3.5. */
+    thickness?: number;
+    /** Show the highest used % beside the ring. Default false. */
+    showLabel?: boolean;
+    /** Click handler (e.g. open usage / upgrade). */
+    onClick?: () => void;
+    /** Delay in ms before the usage popover appears on hover/focus. Default 200. */
+    popoverDelay?: number;
+    /** Period (any datetime in the billing month); defaults to current month. */
+    period?: string;
+    className?: string;
+    'aria-label'?: string;
+};
+
+/** Consumption tier for a used % — drives the blue/amber/red coloring. */
+export declare function usageTier(pct: number): 'normal' | 'warning' | 'critical';
+
+export declare type UsageUnit = 'count' | 'bytes' | 'nano-usd';
+
+export declare function useAddons(): UseQueryResult<Addon[], Error>;
+
+export declare function useBilling(): BillingContextValue;
+
+export declare function useBillingAddress(options?: QueryOptions): UseQueryResult<{
+    address: BillingAddress | null;
+}, Error>;
+
+/** Managed/enterprise locks — when planReadonly, plan changes go through sales. */
+export declare function useBillingReadonly(options?: QueryOptions): UseQueryResult<{
+    planReadonly: boolean;
+    addonsReadonly: boolean;
+}, Error>;
+
+export declare function useCreatePaymentMethodIntent(): UseMutationResult<{
+    clientSecret: string;
+}, Error, void>;
+
+export declare function useCustomer(options?: QueryOptions): UseQueryResult<Customer, Error>;
+
+export declare function useInvoices(options?: QueryOptions): UseQueryResult<{
+    invoices: Invoice[];
+    meta: {
+        nextToken?: string;
+    };
+}, Error>;
+
+export declare function usePaymentMethod(options?: QueryOptions): UseQueryResult<{
+    paymentMethod: PaymentMethod | null;
+}, Error>;
+
+export declare function usePlans(): UseQueryResult<Plan[], Error>;
+
+export declare const UsersIcon: ({ size, ...props }: IconProps) => JSX.Element;
+
+/** Absolute add-on quantities for the current subscription (0 removes an add-on). */
+export declare function useSetAddons(): UseMutationResult<void, Error, {
+    addons: Record<string, number>;
+    couponCode?: string;
+}>;
+
+export declare function useSetBillingAddress(): UseMutationResult<void, Error, BillingAddress>;
+
+export declare function useSetCustomer(): UseMutationResult<Customer, Error, SetCustomerInput>;
+
+export declare function useSetPaymentMethod(): UseMutationResult<PaymentMethod, Error, {
+    paymentMethodId: string;
+}>;
+
+/** Commits the plan (and add-ons when provided), then invalidates everything cost-related. */
+export declare function useSetSubscription(): UseMutationResult<void, Error, SetSubscriptionInput>;
+
+export declare function useSubscription(options?: QueryOptions): UseQueryResult<Subscription, Error>;
+
+/** Proration preview — gate with `enabled` so it only runs while checkout is open. */
+export declare function useSubscriptionPreview(update: SubscriptionUpdate, options?: QueryOptions): UseQueryResult<SubscriptionPreview, Error>;
+
+/** Whether the configured client can serve a per-bot usage breakdown. */
+export declare function useSupportsUsageByBot(): boolean;
+
+/**
+ * Per-feature usage vs. quota for a billing month (defaults to the current month).
+ * Returns the `quotas` map keyed by feature (conversation_sessions, table_rows, …).
+ */
+export declare function useUsage(options?: QueryOptions & {
+    period?: string;
+}): UseQueryResult<WorkspaceUsages, Error>;
+
+/**
+ * Per-bot usage breakdown for a quota type (e.g. ai_spend), joined with bot names.
+ * Returns null when the client doesn't expose the generic per-bot methods (the
+ * billing client alone can't do this) — callers should hide the per-bot UI then.
+ */
+export declare function useUsageByBot(type: string, options?: QueryOptions & {
+    period?: string;
+}): UseQueryResult<BotUsageRow[], Error>;
+
+export declare type WorkspaceUsages = Awaited<ReturnType<BillingClient['getWorkspaceUsages']>>['quotas'];
+
+export { }