@billingos/sdk 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,3346 @@
+import { ClassProp } from 'class-variance-authority/types';
+import { ClassValue } from 'clsx';
+import { default as default_2 } from 'react';
+import { FetchStatus } from '@tanstack/react-query';
+import { JSX } from 'react/jsx-runtime';
+import { QueryClient } from '@tanstack/react-query';
+import { QueryObserverResult } from '@tanstack/react-query';
+import * as React_2 from 'react';
+import { RefetchOptions } from '@tanstack/react-query';
+import { useQueryClient as useBillingOSQueryClient } from '@tanstack/react-query';
+import { UseMutationOptions } from '@tanstack/react-query';
+import { UseMutationResult } from '@tanstack/react-query';
+import { UseQueryOptions } from '@tanstack/react-query';
+import { UseQueryResult } from '@tanstack/react-query';
+import { VariantProps } from 'class-variance-authority';
+
+/**
+ * Add amounts together
+ * @param amounts - Array of amounts in cents
+ * @returns Sum in cents
+ *
+ * @example
+ * addAmounts([1000, 2000, 3000]) // 6000
+ */
+export declare const addAmounts: (...amounts: number[]) => number;
+
+/**
+ * Input for adding a payment method
+ */
+export declare interface AddPaymentMethodInput {
+    paymentMethodId: string;
+    setAsDefault?: boolean;
+}
+
+export declare function AddPaymentMethodModal({ open, onOpenChange, onSuccess, clientSecret, stripePublishableKey, isLoading, }: AddPaymentMethodModalProps): JSX.Element;
+
+declare interface AddPaymentMethodModalProps {
+    open: boolean;
+    onOpenChange: (open: boolean) => void;
+    onSuccess: (paymentMethodId: string, setAsDefault: boolean) => void;
+    clientSecret?: string;
+    stripePublishableKey?: string;
+    isLoading?: boolean;
+}
+
+/**
+ * Response for adding a payment method
+ */
+export declare interface AddPaymentMethodResponse {
+    paymentMethod: PortalPaymentMethod;
+}
+
+export declare const Alert: React_2.ForwardRefExoticComponent<React_2.HTMLAttributes<HTMLDivElement> & VariantProps<(props?: ({
+    variant?: "success" | "default" | "destructive" | "warning" | null | undefined;
+} & ClassProp) | undefined) => string> & React_2.RefAttributes<HTMLDivElement>>;
+
+export declare const AlertDescription: React_2.ForwardRefExoticComponent<React_2.HTMLAttributes<HTMLParagraphElement> & React_2.RefAttributes<HTMLParagraphElement>>;
+
+export declare const AlertTitle: React_2.ForwardRefExoticComponent<React_2.HTMLAttributes<HTMLHeadingElement> & React_2.RefAttributes<HTMLParagraphElement>>;
+
+/**
+ * API error response
+ */
+export declare interface APIErrorResponse {
+    error: {
+        message: string;
+        code?: string;
+        details?: unknown;
+    };
+}
+
+/**
+ * Available plan option
+ */
+export declare interface AvailablePlan {
+    product_id: string;
+    product_name: string;
+    description: string | null;
+    price_id: string;
+    amount: number;
+    currency: string;
+    interval: string;
+    is_free: boolean;
+}
+
+/**
+ * Response from GET /subscriptions/:id/available-plans
+ */
+export declare interface AvailablePlansResponse {
+    current_plan: {
+        product_id: string;
+        product_name: string;
+        price_id: string;
+        amount: number;
+        currency: string;
+        interval: string;
+    } | null;
+    available_upgrades: AvailablePlan[];
+    available_downgrades: AvailablePlan[];
+    restrictions: string[];
+}
+
+export declare function Badge({ className, variant, ...props }: BadgeProps): JSX.Element;
+
+export declare interface BadgeProps extends React_2.HTMLAttributes<HTMLDivElement>, VariantProps<typeof badgeVariants> {
+}
+
+export declare const badgeVariants: (props?: ({
+    variant?: "success" | "default" | "destructive" | "warning" | "secondary" | "outline" | null | undefined;
+} & ClassProp) | undefined) => string;
+
+export declare function BannerNudge({ trigger, onUpgrade, onDismiss, }: BannerNudgeProps): JSX.Element;
+
+export declare interface BannerNudgeProps {
+    trigger: NudgeTrigger;
+    onUpgrade: () => void;
+    onDismiss: () => void;
+    theme?: 'light' | 'dark';
+}
+
+/**
+ * Main BillingOS API client
+ */
+export declare class BillingOSClient {
+    private sessionToken;
+    private baseUrl;
+    private headers;
+    private timeout;
+    constructor(sessionToken: string, options?: BillingOSClientOptions);
+    /**
+     * Internal method to make HTTP requests
+     */
+    private request;
+    /**
+     * GET request helper
+     */
+    get<T>(path: string): Promise<T>;
+    /**
+     * POST request helper
+     */
+    post<T>(path: string, body?: unknown): Promise<T>;
+    /**
+     * PATCH request helper
+     */
+    patch<T>(path: string, body?: unknown): Promise<T>;
+    /**
+     * DELETE request helper
+     */
+    delete<T>(path: string): Promise<T>;
+    /**
+     * Create a new customer
+     */
+    createCustomer(input: CreateCustomerInput): Promise<Customer>;
+    /**
+     * Get a customer by ID
+     */
+    getCustomer(id: string): Promise<Customer>;
+    /**
+     * List customers (paginated)
+     */
+    listCustomers(params?: {
+        page?: number;
+        page_size?: number;
+    }): Promise<PaginatedResponse<Customer>>;
+    /**
+     * Update a customer
+     */
+    updateCustomer(id: string, input: UpdateCustomerInput): Promise<Customer>;
+    /**
+     * Delete a customer
+     */
+    deleteCustomer(id: string): Promise<void>;
+    /**
+     * Create a new subscription
+     */
+    createSubscription(input: CreateSubscriptionInput): Promise<Subscription>;
+    /**
+     * Get a subscription by ID
+     */
+    getSubscription(id: string): Promise<Subscription>;
+    /**
+     * List subscriptions (paginated)
+     */
+    listSubscriptions(params?: {
+        customer_id?: string;
+        page?: number;
+        page_size?: number;
+    }): Promise<PaginatedResponse<Subscription>>;
+    /**
+     * Update a subscription
+     */
+    updateSubscription(id: string, input: UpdateSubscriptionInput): Promise<Subscription>;
+    /**
+     * Cancel a subscription
+     */
+    cancelSubscription(id: string, immediately?: boolean): Promise<Subscription>;
+    /**
+     * Reactivate a canceled subscription
+     */
+    reactivateSubscription(id: string): Promise<Subscription>;
+    /**
+     * Preview subscription changes
+     */
+    previewSubscription(id: string, input: UpdateSubscriptionInput): Promise<SubscriptionPreview>;
+    /**
+     * Get available plans for upgrade/downgrade
+     */
+    getAvailablePlans(subscriptionId: string): Promise<AvailablePlansResponse>;
+    /**
+     * Preview a plan change (upgrade/downgrade) with proration details
+     */
+    previewPlanChange(subscriptionId: string, input: PreviewChangeInput): Promise<PreviewChangeResponse>;
+    /**
+     * Execute a plan change (upgrade/downgrade)
+     */
+    changePlan(subscriptionId: string, input: ChangePlanInput): Promise<ChangePlanResponse>;
+    /**
+     * Check if a customer has access to a feature
+     * Customer ID is resolved server-side from session token
+     */
+    checkEntitlement(input: CheckEntitlementInput): Promise<Entitlement>;
+    /**
+     * List all entitlements for a customer
+     * Customer ID is resolved server-side from session token
+     */
+    listEntitlements(_customerId?: string): Promise<Entitlement[]>;
+    /**
+     * Track a usage event
+     * Customer ID is resolved server-side from session token
+     */
+    trackUsage(event: UsageEvent): Promise<void>;
+    /**
+     * Get usage metrics for a customer and feature
+     * Customer ID is resolved server-side from session token
+     */
+    getUsageMetrics(_customerId?: string, featureKey?: string): Promise<UsageMetrics>;
+    /**
+     * Get an invoice by ID
+     */
+    getInvoice(id: string): Promise<Invoice>;
+    /**
+     * List invoices for a customer
+     */
+    listInvoices(params?: {
+        customer_id?: string;
+        page?: number;
+        page_size?: number;
+    }): Promise<PaginatedResponse<Invoice>>;
+    /**
+     * List payment methods for a customer
+     */
+    listPaymentMethods(customerId: string): Promise<PaymentMethod[]>;
+    /**
+     * Remove a payment method
+     */
+    removePaymentMethod(id: string): Promise<void>;
+    /**
+     * Set default payment method
+     */
+    setDefaultPaymentMethod(id: string): Promise<void>;
+    /**
+     * Get all portal data for the current customer
+     */
+    getCustomerPortal(): Promise<CustomerPortalData>;
+    /**
+     * Update subscription (upgrade/downgrade)
+     */
+    updatePortalSubscription(subscriptionId: string, input: PortalUpdateSubscriptionInput): Promise<PortalUpdateSubscriptionResponse>;
+    /**
+     * Cancel subscription with feedback
+     */
+    cancelPortalSubscription(subscriptionId: string, input: PortalCancelSubscriptionInput): Promise<PortalCancelSubscriptionResponse>;
+    /**
+     * Reactivate a canceled subscription
+     */
+    reactivatePortalSubscription(subscriptionId: string): Promise<void>;
+    /**
+     * Add a payment method
+     */
+    addPaymentMethod(input: AddPaymentMethodInput): Promise<AddPaymentMethodResponse>;
+    /**
+     * Get setup intent for adding a new card
+     */
+    getSetupIntent(): Promise<SetupIntentResponse>;
+    /**
+     * Retry a failed invoice
+     */
+    retryInvoice(invoiceId: string, paymentMethodId?: string): Promise<RetryInvoiceResponse>;
+    /**
+     * Update customer billing information
+     */
+    updateCustomerBilling(input: UpdateCustomerBillingInput): Promise<CustomerBillingInfo>;
+    /**
+     * Create a checkout session for purchasing a subscription
+     */
+    createCheckout(input: CreateCheckoutInput): Promise<CreateCheckoutResponse>;
+    /**
+     * Confirm a checkout after payment is processed
+     */
+    confirmCheckout(clientSecret: string, paymentMethodId: string): Promise<ConfirmCheckoutResponse>;
+    /**
+     * Checkout API methods for iframe-based checkout modal
+     */
+    checkout: {
+        /**
+         * Create a checkout session for iframe-based checkout
+         */
+        createSession: (input: CreateCheckoutSessionInput) => Promise<CreateCheckoutSessionResponse>;
+        /**
+         * Get checkout session details
+         */
+        getSession: (sessionId: string) => Promise<CheckoutSessionDetails>;
+        /**
+         * Cancel a checkout session (not implemented in backend yet)
+         */
+        cancelSession: (_sessionId: string) => Promise<void>;
+        /**
+         * Confirm payment for a checkout session
+         */
+        confirmPayment: (clientSecret: string, paymentMethodId: string) => Promise<ConfirmCheckoutResponse>;
+        /**
+         * Apply coupon to a checkout session (not implemented in backend yet)
+         */
+        applyCoupon: (_sessionId: string, _couponCode: string) => Promise<CheckoutSessionDetails>;
+    };
+    /**
+     * Portal API methods for iframe-based customer portal
+     */
+    portal: {
+        /**
+         * Create a portal session for customer self-service
+         */
+        createSession: (input?: {
+            customerId?: string;
+            metadata?: Record<string, any>;
+        }) => Promise<{
+            id: string;
+            expiresAt: string;
+        }>;
+        /**
+         * Get portal session status
+         */
+        getSessionStatus: (sessionId: string) => Promise<{
+            isValid: boolean;
+            expiresAt?: string;
+        }>;
+        /**
+         * Get portal data for a session
+         */
+        getPortalData: (sessionId: string) => Promise<any>;
+    };
+    /**
+     * Get all products for the pricing table
+     * @param planIds - Optional array of plan IDs to filter
+     */
+    getProducts(planIds?: string[]): Promise<GetProductsResponse>;
+    /**
+     * Check usage and get nudge trigger if applicable
+     * Uses usage-metrics endpoint and computes nudge client-side
+     */
+    checkUsage(): Promise<UsageCheckResponse>;
+}
+
+/**
+ * Configuration options for the BillingOS client
+ */
+export declare interface BillingOSClientOptions {
+    /**
+     * Base URL for the API (defaults to production)
+     */
+    baseUrl?: string;
+    /**
+     * Environment (production or sandbox)
+     */
+    environment?: 'production' | 'sandbox';
+    /**
+     * API version to use
+     */
+    version?: string;
+    /**
+     * Custom headers to include in all requests
+     */
+    headers?: Record<string, string>;
+    /**
+     * Timeout for requests in milliseconds
+     */
+    timeout?: number;
+}
+
+/**
+ * Context value provided by BillingOSProvider
+ */
+export declare interface BillingOSContextValue {
+    /**
+     * The BillingOS API client instance
+     */
+    client: BillingOSClient;
+    /**
+     * Optional customer ID for the current user
+     */
+    customerId?: string;
+    /**
+     * Optional customer email
+     */
+    customerEmail?: string;
+    /**
+     * Optional customer name
+     */
+    customerName?: string;
+    /**
+     * Optional organization ID
+     */
+    organizationId?: string;
+}
+
+/**
+ * Base error class for all BillingOS SDK errors
+ */
+export declare class BillingOSError extends Error {
+    status?: number | undefined;
+    data?: unknown | undefined;
+    constructor(message: string, status?: number | undefined, data?: unknown | undefined);
+}
+
+/**
+ * Provider component for BillingOS SDK
+ *
+ * Wraps your app and provides the BillingOS client to all hooks and components.
+ *
+ * @example
+ * Auto-fetch session token from endpoint:
+ * ```tsx
+ * import { BillingOSProvider } from '@billingos/sdk'
+ *
+ * function App() {
+ *   return (
+ *     <BillingOSProvider
+ *       sessionTokenUrl="/api/billingos-session"
+ *       customerId="customer_123"
+ *     >
+ *       <YourApp />
+ *     </BillingOSProvider>
+ *   )
+ * }
+ * ```
+ *
+ * @example
+ * Manually provide session token:
+ * ```tsx
+ * function App() {
+ *   const [sessionToken, setSessionToken] = useState('bos_session_...')
+ *
+ *   return (
+ *     <BillingOSProvider sessionToken={sessionToken}>
+ *       <YourApp />
+ *     </BillingOSProvider>
+ *   )
+ * }
+ * ```
+ */
+export declare function BillingOSProvider({ sessionToken: manualSessionToken, sessionTokenUrl, sessionTokenOptions, customerId, customerEmail, customerName, organizationId, options, queryClient, children, }: BillingOSProviderProps): JSX.Element | null;
+
+/**
+ * Props for BillingOSProvider
+ */
+export declare interface BillingOSProviderProps {
+    /**
+     * Session token - can be provided directly OR fetched automatically from tokenUrl
+     * Use this when you already have a session token
+     */
+    sessionToken?: string;
+    /**
+     * URL to fetch session token from (e.g., /api/billingos-session)
+     * The SDK will automatically fetch and refresh the token
+     */
+    sessionTokenUrl?: string;
+    /**
+     * Session token options (auto-refresh settings, error handlers, etc.)
+     */
+    sessionTokenOptions?: Omit<UseSessionTokenOptions, 'token' | 'tokenUrl'>;
+    /**
+     * Optional customer ID for the current user
+     */
+    customerId?: string;
+    /**
+     * Optional customer email
+     */
+    customerEmail?: string;
+    /**
+     * Optional customer name
+     */
+    customerName?: string;
+    /**
+     * Optional organization ID
+     */
+    organizationId?: string;
+    /**
+     * Client configuration options
+     */
+    options?: BillingOSClientOptions;
+    /**
+     * Optional custom QueryClient instance
+     * If not provided, a default one will be created
+     */
+    queryClient?: QueryClient;
+    /**
+     * Child components
+     */
+    children: default_2.ReactNode;
+}
+
+export declare const Button: React_2.ForwardRefExoticComponent<ButtonProps & React_2.RefAttributes<HTMLButtonElement>>;
+
+export declare interface ButtonProps extends React_2.ButtonHTMLAttributes<HTMLButtonElement>, VariantProps<typeof buttonVariants> {
+    asChild?: boolean;
+}
+
+export declare const buttonVariants: (props?: ({
+    variant?: "link" | "default" | "destructive" | "secondary" | "outline" | "ghost" | null | undefined;
+    size?: "default" | "sm" | "lg" | "icon" | null | undefined;
+} & ClassProp) | undefined) => string;
+
+/**
+ * Calculate percentage of an amount
+ * @param cents - Amount in cents
+ * @param percentage - Percentage (0-100)
+ * @returns Calculated amount in cents
+ *
+ * @example
+ * calculatePercentage(10000, 20) // 2000 (20% of $100)
+ */
+export declare const calculatePercentage: (cents: number, percentage: number) => number;
+
+export declare function CancelSubscriptionModal({ open, onOpenChange, periodEndDate, onConfirm, isCanceling, }: CancelSubscriptionModalProps): JSX.Element;
+
+declare interface CancelSubscriptionModalProps {
+    open: boolean;
+    onOpenChange: (open: boolean) => void;
+    periodEndDate: string;
+    onConfirm: (input: PortalCancelSubscriptionInput) => void;
+    isCanceling?: boolean;
+}
+
+export declare const Card: React_2.ForwardRefExoticComponent<React_2.HTMLAttributes<HTMLDivElement> & React_2.RefAttributes<HTMLDivElement>>;
+
+export declare const CardContent: React_2.ForwardRefExoticComponent<React_2.HTMLAttributes<HTMLDivElement> & React_2.RefAttributes<HTMLDivElement>>;
+
+export declare const CardDescription: React_2.ForwardRefExoticComponent<React_2.HTMLAttributes<HTMLDivElement> & React_2.RefAttributes<HTMLDivElement>>;
+
+export declare const CardFooter: React_2.ForwardRefExoticComponent<React_2.HTMLAttributes<HTMLDivElement> & React_2.RefAttributes<HTMLDivElement>>;
+
+export declare const CardHeader: React_2.ForwardRefExoticComponent<React_2.HTMLAttributes<HTMLDivElement> & React_2.RefAttributes<HTMLDivElement>>;
+
+export declare const CardTitle: React_2.ForwardRefExoticComponent<React_2.HTMLAttributes<HTMLDivElement> & React_2.RefAttributes<HTMLDivElement>>;
+
+/**
+ * Effective timing for plan changes
+ */
+export declare type ChangeEffectiveTiming = 'immediate' | 'period_end';
+
+/**
+ * Input for changing a plan
+ */
+export declare interface ChangePlanInput {
+    new_price_id: string;
+    confirm_amount?: number;
+    effective_date?: ChangeEffectiveTiming;
+}
+
+export declare function ChangePlanModal({ open, onOpenChange, subscriptionId, onSuccess, }: ChangePlanModalProps): JSX.Element;
+
+declare interface ChangePlanModalProps {
+    open: boolean;
+    onOpenChange: (open: boolean) => void;
+    subscriptionId: string;
+    onSuccess?: () => void;
+}
+
+/**
+ * Response from POST /subscriptions/:id/change-plan
+ */
+export declare interface ChangePlanResponse {
+    subscription: {
+        id: string;
+        status: string;
+        price_id: string;
+        current_period_end: string;
+    };
+    change: {
+        id: string;
+        from_price_id: string;
+        to_price_id: string;
+        change_type: ChangeType;
+        status: string;
+        effective_date: string;
+    };
+    invoice?: {
+        id: string;
+        amount_due: number;
+        status: string;
+    };
+    message: string;
+}
+
+/**
+ * Type of plan change
+ */
+export declare type ChangeType = 'upgrade' | 'downgrade';
+
+export declare const Checkbox: React_2.ForwardRefExoticComponent<CheckboxProps & React_2.RefAttributes<HTMLInputElement>>;
+
+declare interface CheckboxProps extends Omit<React_2.InputHTMLAttributes<HTMLInputElement>, 'type'> {
+    onCheckedChange?: (checked: boolean) => void;
+}
+
+/**
+ * Input for checking entitlements
+ */
+export declare interface CheckEntitlementInput {
+    customer_id: string;
+    feature_key: string;
+}
+
+/**
+ * Programmatic checkout API
+ */
+export declare class CheckoutAPI {
+    private client?;
+    private container?;
+    private root?;
+    constructor(client?: BillingOSClient);
+    /**
+     * Open the checkout modal programmatically
+     */
+    open(options: CheckoutOpenOptions): Promise<{
+        success: boolean;
+        subscription?: Subscription;
+        error?: Error;
+    }>;
+    /**
+     * Close the checkout modal
+     */
+    close(): void;
+}
+
+/**
+ * Customer info for checkout
+ */
+export declare interface CheckoutCustomer {
+    email: string;
+    name: string;
+}
+
+export declare function CheckoutModal({ open, onOpenChange, priceId, customer, couponCode, collectBillingAddress, existingSubscriptionId, metadata, theme, locale, onSuccess, onError, onCancel, debug }: CheckoutModalProps): JSX.Element;
+
+export declare interface CheckoutModalProps {
+    /**
+     * Whether the modal is open
+     */
+    open: boolean;
+    /**
+     * Callback when the modal open state changes
+     */
+    onOpenChange: (open: boolean) => void;
+    /**
+     * The price ID to checkout
+     */
+    priceId: string;
+    /**
+     * Customer information to pre-populate
+     */
+    customer?: {
+        email?: string;
+        name?: string;
+        taxId?: string;
+    };
+    /**
+     * Coupon code to apply
+     */
+    couponCode?: string;
+    /**
+     * Whether to collect billing address
+     */
+    collectBillingAddress?: boolean;
+    /**
+     * Currency for the checkout (defaults to price currency)
+     */
+    currency?: string;
+    /**
+     * Existing subscription ID for upgrades/downgrades
+     */
+    existingSubscriptionId?: string;
+    /**
+     * Custom metadata to attach to the subscription
+     */
+    metadata?: Record<string, string>;
+    /**
+     * Theme for the checkout modal
+     */
+    theme?: 'light' | 'dark' | 'auto';
+    /**
+     * Locale for the checkout (e.g., 'en', 'es', 'fr')
+     */
+    locale?: string;
+    /**
+     * Success callback with the created subscription
+     */
+    onSuccess: (subscription: any) => void;
+    /**
+     * Error callback
+     */
+    onError?: (error: Error) => void;
+    /**
+     * Cancel callback when user closes without completing
+     */
+    onCancel?: () => void;
+    /**
+     * Debug mode for development
+     */
+    debug?: boolean;
+}
+
+/**
+ * Options for opening the checkout modal programmatically
+ */
+export declare interface CheckoutOpenOptions {
+    /**
+     * The price ID to checkout
+     */
+    priceId: string;
+    /**
+     * Customer information to pre-populate
+     */
+    customer?: {
+        email?: string;
+        name?: string;
+        taxId?: string;
+    };
+    /**
+     * Coupon code to apply
+     */
+    couponCode?: string;
+    /**
+     * Whether to collect billing address
+     */
+    collectBillingAddress?: boolean;
+    /**
+     * Currency for the checkout (defaults to price currency)
+     */
+    currency?: string;
+    /**
+     * Existing subscription ID for upgrades/downgrades
+     */
+    existingSubscriptionId?: string;
+    /**
+     * Custom metadata to attach to the subscription
+     */
+    metadata?: Record<string, string>;
+    /**
+     * Theme for the checkout modal
+     */
+    theme?: 'light' | 'dark' | 'auto';
+    /**
+     * Locale for the checkout (e.g., 'en', 'es', 'fr')
+     */
+    locale?: string;
+    /**
+     * Success callback with the created subscription
+     */
+    onSuccess?: (subscription: Subscription) => void;
+    /**
+     * Error callback
+     */
+    onError?: (error: Error) => void;
+    /**
+     * Cancel callback when user closes without completing
+     */
+    onCancel?: () => void;
+    /**
+     * Debug mode for development
+     */
+    debug?: boolean;
+    /**
+     * Session token for authentication (if not using provider)
+     */
+    sessionToken?: string;
+    /**
+     * API base URL (if not using provider)
+     */
+    apiUrl?: string;
+}
+
+/**
+ * Product summary for checkout
+ */
+export declare interface CheckoutProduct {
+    name: string;
+    interval: 'day' | 'week' | 'month' | 'year';
+    features: string[];
+}
+
+/**
+ * Proration details for subscription changes
+ */
+export declare interface CheckoutProration {
+    credited: number;
+    charged: number;
+    total: number;
+    explanation: string;
+}
+
+/**
+ * Result from opening checkout
+ */
+export declare interface CheckoutResult {
+    success: boolean;
+    subscription?: Subscription;
+    error?: Error;
+}
+
+/**
+ * Checkout session returned by the API
+ */
+export declare interface CheckoutSession {
+    id: string;
+    clientSecret: string;
+    amount: number;
+    currency: string;
+    proration?: CheckoutProration;
+    product: CheckoutProduct;
+    customer: CheckoutCustomer;
+    stripeAccountId?: string;
+}
+
+/**
+ * Detailed checkout session information
+ */
+export declare interface CheckoutSessionDetails {
+    id: string;
+    clientSecret: string;
+    amount: number;
+    currency: string;
+    priceId: string;
+    product: CheckoutProduct;
+    customer: CheckoutCustomer;
+    couponCode?: string;
+    discountAmount?: number;
+    taxAmount?: number;
+    totalAmount: number;
+    proration?: CheckoutProration;
+    status: 'pending' | 'processing' | 'completed' | 'failed' | 'expired';
+    expiresAt: string;
+    stripeAccountId?: string;
+}
+
+/**
+ * Utility function to merge Tailwind CSS classes
+ * Combines clsx for conditional classes with tailwind-merge for deduplication
+ */
+export declare function cn(...inputs: ClassValue[]): string;
+
+/**
+ * Compact upgrade prompt for inline use
+ */
+export declare function CompactUpgradePrompt({ feature, onUpgradeClick, className, }: {
+    feature?: string;
+    onUpgradeClick?: () => void;
+    className?: string;
+}): JSX.Element;
+
+/**
+ * Compact usage display for inline use
+ */
+export declare function CompactUsageDisplay({ featureKey, className, }: {
+    featureKey: string;
+    className?: string;
+}): JSX.Element | null;
+
+/**
+ * Input for confirming a checkout
+ */
+export declare interface ConfirmCheckoutInput {
+    paymentMethodId: string;
+}
+
+/**
+ * Response from confirming a checkout
+ */
+export declare interface ConfirmCheckoutResponse {
+    success: boolean;
+    subscriptionId: string;
+    status: 'active' | 'trialing';
+    message: string;
+}
+
+/**
+ * Convert cents to float (dollars)
+ * @param cents - Amount in cents
+ * @returns Amount in dollars as a float
+ *
+ * @example
+ * convertCentsToFloat(1050) // 10.5
+ */
+export declare const convertCentsToFloat: (cents: number) => number;
+
+/**
+ * Convert float (dollars) to cents
+ * @param amount - Amount in dollars
+ * @returns Amount in cents as an integer
+ *
+ * @example
+ * convertFloatToCents(10.5) // 1050
+ */
+export declare const convertFloatToCents: (amount: number) => number;
+
+/**
+ * Factory function to create a BillingOS client instance
+ */
+export declare function createBillingOSClient(sessionToken: string, options?: BillingOSClientOptions): BillingOSClient;
+
+/**
+ * Input for creating a checkout session
+ */
+export declare interface CreateCheckoutInput {
+    priceId: string;
+    customerEmail?: string;
+    customerName?: string;
+    existingSubscriptionId?: string;
+}
+
+/**
+ * Response from creating a checkout session
+ * The API returns the checkout session directly
+ */
+export declare type CreateCheckoutResponse = CheckoutSession;
+
+/**
+ * Input for creating an iframe checkout session
+ */
+export declare interface CreateCheckoutSessionInput {
+    priceId: string;
+    customer?: {
+        email?: string;
+        name?: string;
+        taxId?: string;
+    };
+    couponCode?: string;
+    metadata?: Record<string, string>;
+    existingSubscriptionId?: string;
+    mode?: 'embedded' | 'redirect';
+    successUrl?: string;
+    cancelUrl?: string;
+}
+
+/**
+ * Response from creating a checkout session
+ */
+export declare interface CreateCheckoutSessionResponse {
+    id: string;
+    url?: string;
+    expiresAt: string;
+    status: 'pending' | 'completed' | 'expired';
+}
+
+/**
+ * Input for creating a customer
+ */
+export declare interface CreateCustomerInput {
+    email: string;
+    name?: string;
+    metadata?: Record<string, string>;
+}
+
+/**
+ * Input for creating a subscription
+ */
+export declare interface CreateSubscriptionInput {
+    customer_id: string;
+    price_id: string;
+    trial_days?: number;
+    metadata?: Record<string, string>;
+}
+
+/**
+ * Customer represents a billing customer
+ */
+export declare interface Customer {
+    id: string;
+    email: string;
+    name?: string;
+    metadata?: Record<string, string>;
+    created_at: string;
+    updated_at: string;
+}
+
+/**
+ * Customer billing info response
+ */
+export declare interface CustomerBillingInfo {
+    id: string;
+    email: string;
+    name: string;
+    billingAddress?: PortalAddress;
+}
+
+export declare function CustomerPortal({ isOpen, onClose, mode, defaultTab, theme, className, customerId, metadata, onSubscriptionUpdate, onSubscriptionCancel, onPaymentMethodAdd, onPaymentMethodUpdate, debug }: CustomerPortalProps): JSX.Element;
+
+/**
+ * Complete portal data from API
+ */
+export declare interface CustomerPortalData {
+    subscription: PortalSubscription | null;
+    invoices: PortalInvoice[];
+    paymentMethods: PortalPaymentMethod[];
+    customer: PortalCustomer;
+    availablePlans: PortalAvailablePlan[];
+}
+
+export declare interface CustomerPortalProps {
+    /**
+     * Open/close state (for drawer/modal mode)
+     */
+    isOpen?: boolean;
+    /**
+     * Callback when user closes portal
+     */
+    onClose?: () => void;
+    /**
+     * Display mode
+     * - 'drawer': Slide-in from right (default)
+     * - 'modal': Centered modal
+     * - 'page': Full-page view
+     */
+    mode?: 'drawer' | 'modal' | 'page';
+    /**
+     * Default tab to show
+     */
+    defaultTab?: PortalTab;
+    /**
+     * Optional: Custom theme
+     */
+    theme?: 'light' | 'dark';
+    /**
+     * Optional: Custom class name
+     */
+    className?: string;
+    /**
+     * Optional: Customer ID to load specific customer
+     */
+    customerId?: string;
+    /**
+     * Optional: Custom metadata
+     */
+    metadata?: Record<string, any>;
+    /**
+     * Callback when subscription is updated
+     */
+    onSubscriptionUpdate?: (subscription: any) => void;
+    /**
+     * Callback when subscription is cancelled
+     */
+    onSubscriptionCancel?: () => void;
+    /**
+     * Callback when payment method is added
+     */
+    onPaymentMethodAdd?: () => void;
+    /**
+     * Callback when payment method is updated
+     */
+    onPaymentMethodUpdate?: () => void;
+    /**
+     * Debug mode for development
+     */
+    debug?: boolean;
+}
+
+/**
+ * Date utilities namespace
+ */
+export declare const DateUtils: {
+    format: (date: string | Date, formatStr?: string) => string;
+    formatRelative: (date: string | Date, baseDate?: Date) => string;
+    formatRelativeDate: (date: string | Date, baseDate?: Date) => string;
+    isPast: (date: string | Date) => boolean;
+    isFuture: (date: string | Date) => boolean;
+    parse: (date: string) => Date;
+};
+
+export declare function Dialog({ open, onOpenChange, children }: DialogProps): JSX.Element;
+
+export declare const DialogContent: React_2.ForwardRefExoticComponent<React_2.HTMLAttributes<HTMLDivElement> & React_2.RefAttributes<HTMLDivElement>>;
+
+export declare const DialogDescription: React_2.ForwardRefExoticComponent<React_2.HTMLAttributes<HTMLParagraphElement> & React_2.RefAttributes<HTMLParagraphElement>>;
+
+export declare const DialogFooter: {
+    ({ className, ...props }: React_2.HTMLAttributes<HTMLDivElement>): JSX.Element;
+    displayName: string;
+};
+
+export declare const DialogHeader: {
+    ({ className, ...props }: React_2.HTMLAttributes<HTMLDivElement>): JSX.Element;
+    displayName: string;
+};
+
+export declare const DialogOverlay: React_2.ForwardRefExoticComponent<React_2.HTMLAttributes<HTMLDivElement> & React_2.RefAttributes<HTMLDivElement>>;
+
+export declare function DialogPortal({ children }: DialogPortalProps): JSX.Element | null;
+
+declare interface DialogPortalProps {
+    children: React_2.ReactNode;
+}
+
+declare interface DialogProps {
+    open?: boolean;
+    onOpenChange?: (open: boolean) => void;
+    children: React_2.ReactNode;
+}
+
+export declare const DialogTitle: React_2.ForwardRefExoticComponent<React_2.HTMLAttributes<HTMLHeadingElement> & React_2.RefAttributes<HTMLHeadingElement>>;
+
+export declare const DialogTrigger: React_2.ForwardRefExoticComponent<DialogTriggerProps & React_2.RefAttributes<HTMLButtonElement>>;
+
+declare interface DialogTriggerProps extends React_2.ButtonHTMLAttributes<HTMLButtonElement> {
+    asChild?: boolean;
+}
+
+export declare function Drawer({ open, onOpenChange, children }: DrawerProps): JSX.Element;
+
+export declare const DrawerClose: React_2.ForwardRefExoticComponent<React_2.ButtonHTMLAttributes<HTMLButtonElement> & React_2.RefAttributes<HTMLButtonElement>>;
+
+export declare const DrawerContent: React_2.ForwardRefExoticComponent<DrawerContentProps & React_2.RefAttributes<HTMLDivElement>>;
+
+declare interface DrawerContentProps extends React_2.HTMLAttributes<HTMLDivElement> {
+    /**
+     * Whether to prevent closing when clicking outside or pressing ESC
+     */
+    preventClose?: boolean;
+    /**
+     * Callback when user attempts to close but it's prevented
+     */
+    onCloseAttempt?: () => void;
+}
+
+export declare const DrawerDescription: React_2.ForwardRefExoticComponent<React_2.HTMLAttributes<HTMLParagraphElement> & React_2.RefAttributes<HTMLParagraphElement>>;
+
+export declare const DrawerFooter: {
+    ({ className, ...props }: React_2.HTMLAttributes<HTMLDivElement>): JSX.Element;
+    displayName: string;
+};
+
+export declare const DrawerHeader: {
+    ({ className, ...props }: React_2.HTMLAttributes<HTMLDivElement>): JSX.Element;
+    displayName: string;
+};
+
+declare interface DrawerProps {
+    open?: boolean;
+    onOpenChange?: (open: boolean) => void;
+    children: React_2.ReactNode;
+}
+
+export declare const DrawerTitle: React_2.ForwardRefExoticComponent<React_2.HTMLAttributes<HTMLHeadingElement> & React_2.RefAttributes<HTMLHeadingElement>>;
+
+export declare const DrawerTrigger: React_2.ForwardRefExoticComponent<DrawerTriggerProps & React_2.RefAttributes<HTMLButtonElement>>;
+
+declare interface DrawerTriggerProps extends React_2.ButtonHTMLAttributes<HTMLButtonElement> {
+    asChild?: boolean;
+}
+
+/**
+ * Entitlement represents a feature access grant
+ */
+export declare interface Entitlement {
+    feature_key: string;
+    has_access: boolean;
+    limit?: number;
+    usage?: number;
+    metadata?: Record<string, string>;
+}
+
+/**
+ * Query keys for entitlement-related queries
+ */
+export declare const entitlementKeys: {
+    all: readonly ["entitlements"];
+    lists: () => readonly ["entitlements", "list"];
+    list: (customerId: string) => readonly ["entitlements", "list", string];
+    checks: () => readonly ["entitlements", "check"];
+    check: (customerId: string, featureKey: string) => readonly ["entitlements", "check", string, string];
+    usage: (customerId: string, featureKey: string) => readonly ["entitlements", "usage", string, string];
+};
+
+/**
+ * Feature access response
+ */
+export declare interface FeatureAccess {
+    feature_key: string;
+    has_access: boolean;
+    limit?: number;
+    usage?: number;
+    metadata?: Record<string, any>;
+}
+
+/**
+ * Feature entitlement
+ */
+export declare interface FeatureEntitlement {
+    feature_key: string;
+    feature_title: string;
+    feature_type: 'boolean_flag' | 'usage_quota' | 'numeric_limit';
+    granted_at: string;
+    product_name: string;
+    subscription_status: string;
+    properties?: Record<string, any>;
+}
+
+/**
+ * FeatureGate component for conditional rendering based on feature access
+ *
+ * @example
+ * ```tsx
+ * <FeatureGate
+ *   feature="advanced_analytics"
+ *   fallback={<UpgradePrompt feature="Advanced Analytics" />}
+ * >
+ *   <AdvancedAnalyticsDashboard />
+ * </FeatureGate>
+ * ```
+ */
+export declare function FeatureGate({ feature, children, fallback, loading, onAccessDenied, onQuotaExceeded, showUsageBadge, }: FeatureGateProps): JSX.Element;
+
+export declare interface FeatureGateProps {
+    /**
+     * The feature key to check access for
+     */
+    feature: string;
+    /**
+     * Content to render when user has access
+     */
+    children: default_2.ReactNode;
+    /**
+     * Content to render when access is denied (optional)
+     */
+    fallback?: default_2.ReactNode;
+    /**
+     * Content to render while loading (optional)
+     */
+    loading?: default_2.ReactNode;
+    /**
+     * Callback when access is denied
+     */
+    onAccessDenied?: () => void;
+    /**
+     * Callback when quota is exceeded
+     */
+    onQuotaExceeded?: (usage: number, limit: number) => void;
+    /**
+     * Whether to show remaining usage in a badge
+     */
+    showUsageBadge?: boolean;
+}
+
+export declare function FeatureList({ features, className }: FeatureListProps): JSX.Element | null;
+
+declare interface FeatureListProps {
+    features: PortalFeatureWithUsage[];
+    className?: string;
+}
+
+/**
+ * Format cents as currency with symbol
+ * @param cents - Amount in cents
+ * @param currency - Currency code (e.g., 'USD', 'EUR')
+ * @param minimumFractionDigits - Minimum decimal places
+ * @param notation - Number notation style
+ * @param maximumFractionDigits - Maximum decimal places
+ * @returns Formatted currency string with symbol
+ *
+ * @example
+ * formatCurrencyAndAmount(1050, 'USD') // "$10.50"
+ * formatCurrencyAndAmount(1000000, 'USD', 0, 'compact') // "$10K"
+ * formatCurrencyAndAmount(5000, 'EUR') // "€50.00"
+ */
+export declare const formatCurrencyAndAmount: (cents: number, currency: string, minimumFractionDigits?: number, notation?: "standard" | "scientific" | "engineering" | "compact", maximumFractionDigits?: number) => string;
+
+/**
+ * Format currency in compact notation (e.g., $1.2K, $3.5M)
+ * @param cents - Amount in cents
+ * @param currency - Currency code
+ * @returns Compact formatted currency string
+ *
+ * @example
+ * formatCurrencyCompact(1200000, 'USD') // "$12K"
+ * formatCurrencyCompact(3500000000, 'USD') // "$35M"
+ */
+export declare const formatCurrencyCompact: (cents: number, currency: string) => string;
+
+/**
+ * Format currency without cents (whole dollars only)
+ * @param cents - Amount in cents
+ * @param currency - Currency code
+ * @returns Formatted currency string without cents
+ *
+ * @example
+ * formatCurrencyWhole(1050, 'USD') // "$10"
+ * formatCurrencyWhole(1099, 'USD') // "$11" (rounds)
+ */
+export declare const formatCurrencyWhole: (cents: number, currency: string) => string;
+
+/**
+ * Format a date string or Date object
+ * @param date - Date string (ISO) or Date object
+ * @param formatStr - Format string (date-fns format)
+ * @returns Formatted date string
+ *
+ * @example
+ * formatDate('2024-01-15T10:30:00Z', 'PPP') // "January 15th, 2024"
+ * formatDate(new Date(), 'yyyy-MM-dd') // "2024-01-15"
+ */
+export declare const formatDate: (date: string | Date, formatStr?: string) => string;
+
+/**
+ * Format a price range (e.g., "$10 - $50")
+ * @param minCents - Minimum amount in cents
+ * @param maxCents - Maximum amount in cents
+ * @param currency - Currency code
+ * @returns Formatted price range string
+ *
+ * @example
+ * formatPriceRange(1000, 5000, 'USD') // "$10 - $50"
+ */
+export declare const formatPriceRange: (minCents: number, maxCents: number, currency: string) => string;
+
+/**
+ * Format a date relative to now (e.g., "today at 10:30 AM")
+ * @param date - Date string (ISO) or Date object
+ * @param baseDate - Base date to compare against (defaults to now)
+ * @returns Relative date string
+ *
+ * @example
+ * formatRelativeDate('2024-01-15T10:30:00Z') // "today at 10:30 AM"
+ */
+export declare const formatRelativeDate: (date: string | Date, baseDate?: Date) => string;
+
+/**
+ * Format a date as relative time (e.g., "2 hours ago")
+ * @param date - Date string (ISO) or Date object
+ * @param baseDate - Base date to compare against (defaults to now)
+ * @returns Relative time string
+ *
+ * @example
+ * formatRelativeTime('2024-01-15T08:30:00Z') // "2 hours ago"
+ */
+export declare const formatRelativeTime: (date: string | Date, baseDate?: Date) => string;
+
+/**
+ * Convert cents to dollar string
+ * @param cents - Amount in cents
+ * @param showCents - Force showing cents even if amount is whole dollars
+ * @param pretty - Use locale formatting with thousand separators
+ * @returns Formatted dollar string
+ *
+ * @example
+ * getCentsInDollarString(1000) // "10"
+ * getCentsInDollarString(1050, true) // "10.50"
+ * getCentsInDollarString(1000000, false, true) // "10,000"
+ */
+export declare const getCentsInDollarString: (cents: number, showCents?: boolean, pretty?: boolean) => string;
+
+/**
+ * Get or create the global checkout API instance
+ */
+export declare function getCheckoutAPI(client?: BillingOSClient): CheckoutAPI;
+
+/**
+ * Get currency symbol for a currency code
+ * @param currency - Currency code (e.g., 'USD', 'EUR')
+ * @returns Currency symbol (e.g., '$', '€')
+ *
+ * @example
+ * getCurrencySymbol('USD') // "$"
+ * getCurrencySymbol('EUR') // "€"
+ * getCurrencySymbol('GBP') // "£"
+ */
+export declare const getCurrencySymbol: (currency: string) => string;
+
+/**
+ * Response from GET /sdk/products
+ */
+export declare interface GetProductsResponse {
+    products: PricingProduct[];
+    currentSubscription: PricingCurrentSubscription | null;
+}
+
+export declare const Input: React_2.ForwardRefExoticComponent<Omit<React_2.DetailedHTMLProps<React_2.InputHTMLAttributes<HTMLInputElement>, HTMLInputElement>, "ref"> & React_2.RefAttributes<HTMLInputElement>>;
+
+/**
+ * Invoice represents a billing invoice
+ */
+export declare interface Invoice {
+    id: string;
+    customer_id: string;
+    amount_due: number;
+    amount_paid: number;
+    currency: string;
+    status: 'draft' | 'open' | 'paid' | 'uncollectible' | 'void';
+    due_date?: string;
+    paid_at?: string;
+    invoice_pdf?: string;
+    created_at: string;
+}
+
+export declare function InvoiceCard({ invoice, onRetry, onDownload, isRetrying, className, }: InvoiceCardProps): JSX.Element;
+
+declare interface InvoiceCardProps {
+    invoice: PortalInvoice;
+    onRetry?: (invoiceId: string) => void;
+    onDownload?: (pdfUrl: string) => void;
+    isRetrying?: boolean;
+    className?: string;
+}
+
+export declare function InvoicesTab({ invoices, onRetryInvoice, onDownloadInvoice, retryingInvoiceId, isLoading, className, }: InvoicesTabProps): JSX.Element;
+
+declare interface InvoicesTabProps {
+    invoices: PortalInvoice[];
+    onRetryInvoice: (invoiceId: string) => void;
+    onDownloadInvoice: (pdfUrl: string) => void;
+    retryingInvoiceId?: string;
+    isLoading?: boolean;
+    className?: string;
+}
+
+/**
+ * Check if a date is in the future
+ * @param date - Date string (ISO) or Date object
+ * @returns True if date is in the future
+ */
+export declare const isFuture: (date: string | Date) => boolean;
+
+/**
+ * Check if an amount is negative
+ * @param cents - Amount in cents
+ * @returns True if amount is negative
+ */
+export declare const isNegativeAmount: (cents: number) => boolean;
+
+/**
+ * Type guard to check if an error is a not found error
+ */
+export declare function isNotFoundError(error: unknown): error is NotFoundError;
+
+/**
+ * Check if a date is in the past
+ * @param date - Date string (ISO) or Date object
+ * @returns True if date is in the past
+ */
+export declare const isPast: (date: string | Date) => boolean;
+
+/**
+ * Type guard to check if an error is a rate limit error
+ */
+export declare function isRateLimitError(error: unknown): error is RateLimitError;
+
+/**
+ * Type guard to check if an error is an unauthorized error
+ */
+export declare function isUnauthorizedError(error: unknown): error is UnauthorizedError;
+
+/**
+ * Type guard to check if an error is a validation error
+ */
+export declare function isValidationError(error: unknown): error is ValidationError;
+
+/**
+ * Check if an amount is zero
+ * @param cents - Amount in cents
+ * @returns True if amount is zero
+ */
+export declare const isZeroAmount: (cents: number) => boolean;
+
+export declare const Label: React_2.ForwardRefExoticComponent<LabelProps & React_2.RefAttributes<HTMLLabelElement>>;
+
+export declare interface LabelProps extends React_2.LabelHTMLAttributes<HTMLLabelElement>, VariantProps<typeof labelVariants> {
+}
+
+declare const labelVariants: (props?: ClassProp | undefined) => string;
+
+export declare function ModalNudge({ trigger, onUpgrade, onDismiss, }: ModalNudgeProps): JSX.Element;
+
+export declare interface ModalNudgeProps {
+    trigger: NudgeTrigger;
+    onUpgrade: () => void;
+    onDismiss: () => void;
+    theme?: 'light' | 'dark';
+}
+
+/**
+ * Money utilities namespace for convenience
+ */
+export declare const Money: {
+    format: (cents: number, currency: string, minimumFractionDigits?: number, notation?: "standard" | "scientific" | "engineering" | "compact", maximumFractionDigits?: number) => string;
+    formatCompact: (cents: number, currency: string) => string;
+    formatWhole: (cents: number, currency: string) => string;
+    formatRange: (minCents: number, maxCents: number, currency: string) => string;
+    fromCents: (cents: number) => number;
+    toCents: (amount: number) => number;
+    getSymbol: (currency: string) => string;
+    isZero: (cents: number) => boolean;
+    isNegative: (cents: number) => boolean;
+    calculatePercentage: (cents: number, percentage: number) => number;
+    add: (...amounts: number[]) => number;
+};
+
+/**
+ * Thrown when the network request fails
+ */
+export declare class NetworkError extends BillingOSError {
+    constructor(message?: string, originalError?: unknown);
+}
+
+/**
+ * Thrown when the requested resource is not found (404)
+ */
+export declare class NotFoundError extends BillingOSError {
+    constructor(message?: string, data?: unknown);
+}
+
+/**
+ * Message content for nudge
+ */
+export declare interface NudgeMessage {
+    title: string;
+    body: string;
+    cta: string;
+}
+
+/**
+ * Nudge trigger data
+ */
+export declare interface NudgeTrigger {
+    type: NudgeTriggerType;
+    feature?: string;
+    threshold?: number;
+    actual?: number;
+    message: NudgeMessage;
+    suggestedPlan: SuggestedPlan;
+}
+
+/**
+ * Type of nudge trigger
+ */
+export declare type NudgeTriggerType = 'usage_threshold' | 'feature_access' | 'time_based' | 'custom';
+
+/**
+ * Convenience function to open checkout modal
+ */
+export declare function openCheckout(options: CheckoutOpenOptions): Promise<{
+    success: boolean;
+    subscription?: Subscription;
+    error?: Error;
+}>;
+
+/**
+ * Paginated response wrapper
+ */
+export declare interface PaginatedResponse<T> {
+    data: T[];
+    meta: PaginationMeta;
+}
+
+/**
+ * Pagination metadata
+ */
+export declare interface PaginationMeta {
+    total: number;
+    page: number;
+    page_size: number;
+    total_pages: number;
+}
+
+/**
+ * Parse ISO date string to Date object
+ * @param date - ISO date string
+ * @returns Date object
+ */
+export declare const parseDate: (date: string) => Date;
+
+export declare function PaymentBottomSheet({ priceId, isOpen, onClose, onSuccess, existingSubscriptionId, theme, }: PaymentBottomSheetProps): JSX.Element;
+
+export declare interface PaymentBottomSheetProps {
+    /**
+     * Price ID to purchase
+     */
+    priceId: string;
+    /**
+     * Open/close state
+     */
+    isOpen: boolean;
+    /**
+     * Callback when user closes sheet
+     */
+    onClose: () => void;
+    /**
+     * Callback when payment succeeds
+     */
+    onSuccess: (subscriptionId: string) => void;
+    /**
+     * Optional: Subscription ID if upgrading
+     */
+    existingSubscriptionId?: string;
+    /**
+     * Optional: Custom theme
+     */
+    theme?: 'light' | 'dark';
+}
+
+/**
+ * Payment method
+ */
+export declare interface PaymentMethod {
+    id: string;
+    type: 'card' | 'bank_account';
+    card?: {
+        brand: string;
+        last4: string;
+        exp_month: number;
+        exp_year: number;
+    };
+    is_default: boolean;
+    created_at: string;
+}
+
+export declare function PaymentMethodCard({ paymentMethod, onSetDefault, onRemove, isSettingDefault, isRemoving, className, }: PaymentMethodCardProps): JSX.Element | null;
+
+declare interface PaymentMethodCardProps {
+    paymentMethod: PortalPaymentMethod;
+    onSetDefault?: (id: string) => void;
+    onRemove?: (id: string) => void;
+    isSettingDefault?: boolean;
+    isRemoving?: boolean;
+    className?: string;
+}
+
+export declare function PaymentMethodsTab({ paymentMethods, onAddPaymentMethod, onSetDefault, onRemove, settingDefaultId, removingId, isLoading, className, }: PaymentMethodsTabProps): JSX.Element;
+
+declare interface PaymentMethodsTabProps {
+    paymentMethods: PortalPaymentMethod[];
+    onAddPaymentMethod: () => void;
+    onSetDefault: (id: string) => void;
+    onRemove: (id: string) => void;
+    settingDefaultId?: string;
+    removingId?: string;
+    isLoading?: boolean;
+    className?: string;
+}
+
+/**
+ * Plan information
+ */
+export declare interface PlanInfo {
+    product_id: string;
+    product_name: string;
+    price_id: string;
+    amount: number;
+    currency: string;
+    interval: string;
+}
+
+/**
+ * Billing address
+ */
+export declare interface PortalAddress {
+    line1: string;
+    line2?: string;
+    city: string;
+    state: string;
+    postalCode: string;
+    country: string;
+}
+
+/**
+ * Available plan for upgrade/downgrade
+ */
+export declare interface PortalAvailablePlan {
+    id: string;
+    name: string;
+    price: {
+        amount: number;
+        currency: string;
+        interval: 'day' | 'week' | 'month' | 'year';
+    };
+    type: 'upgrade' | 'downgrade' | 'current';
+}
+
+/**
+ * Input for canceling subscription via portal
+ */
+export declare interface PortalCancelSubscriptionInput {
+    cancelAtPeriodEnd: boolean;
+    cancellationReason?: 'too_expensive' | 'missing_features' | 'found_alternative' | 'no_longer_needed' | 'other';
+    feedback?: string;
+}
+
+/**
+ * Response for subscription cancellation
+ */
+export declare interface PortalCancelSubscriptionResponse {
+    subscription: {
+        id: string;
+        status: string;
+        cancelAtPeriodEnd: boolean;
+        canceledAt: string;
+        currentPeriodEnd: string;
+    };
+    message: string;
+}
+
+/**
+ * Card details for portal
+ */
+export declare interface PortalCardDetails {
+    brand: 'visa' | 'mastercard' | 'amex' | 'discover' | 'diners' | 'jcb' | 'unionpay';
+    last4: string;
+    expMonth: number;
+    expYear: number;
+}
+
+/**
+ * Customer details for portal
+ */
+export declare interface PortalCustomer {
+    id: string;
+    email: string;
+    name: string;
+    billingAddress?: PortalAddress;
+}
+
+/**
+ * Feature type for portal
+ */
+export declare type PortalFeatureType = 'boolean_flag' | 'usage_quota' | 'numeric_limit';
+
+/**
+ * Feature with usage tracking for portal
+ */
+export declare interface PortalFeatureWithUsage {
+    id: string;
+    name: string;
+    title: string;
+    type: PortalFeatureType;
+    properties: Record<string, unknown>;
+    usage?: PortalUsageInfo;
+    enabled?: boolean;
+}
+
+/**
+ * Invoice details for portal
+ */
+export declare interface PortalInvoice {
+    id: string;
+    number: string;
+    date: string;
+    dueDate: string;
+    status: 'paid' | 'open' | 'failed' | 'void';
+    amount: number;
+    currency: string;
+    pdfUrl: string | null;
+    lineItems: PortalLineItem[];
+    failureReason?: string;
+}
+
+/**
+ * Query keys for portal-related queries
+ */
+export declare const portalKeys: {
+    all: readonly ["portal"];
+    data: () => readonly ["portal", "data"];
+    setupIntent: () => readonly ["portal", "setupIntent"];
+};
+
+/**
+ * Line item in an invoice
+ */
+export declare interface PortalLineItem {
+    description: string;
+    quantity: number;
+    amount: number;
+}
+
+/**
+ * Payment method for portal
+ */
+export declare interface PortalPaymentMethod {
+    id: string;
+    type: 'card' | 'bank_account';
+    card?: PortalCardDetails;
+    isDefault: boolean;
+}
+
+/**
+ * Price information for portal
+ */
+export declare interface PortalPrice {
+    id: string;
+    amount: number;
+    currency: string;
+    interval: 'day' | 'week' | 'month' | 'year';
+    intervalCount: number;
+}
+
+/**
+ * Product information for portal
+ */
+export declare interface PortalProduct {
+    id: string;
+    name: string;
+    description?: string;
+}
+
+/**
+ * Subscription details for portal
+ */
+export declare interface PortalSubscription {
+    id: string;
+    status: 'active' | 'trialing' | 'past_due' | 'canceled' | 'unpaid';
+    product: PortalProduct;
+    price: PortalPrice;
+    currentPeriodStart: string;
+    currentPeriodEnd: string;
+    cancelAtPeriodEnd: boolean;
+    trialEnd: string | null;
+    canceledAt: string | null;
+    features: PortalFeatureWithUsage[];
+}
+
+declare type PortalTab = 'subscription' | 'invoices' | 'payment' | 'settings';
+
+/**
+ * Input for updating subscription via portal
+ */
+export declare interface PortalUpdateSubscriptionInput {
+    newPriceId: string;
+    prorationBehavior?: 'always_invoice' | 'create_prorations' | 'none';
+}
+
+/**
+ * Response for subscription update
+ */
+export declare interface PortalUpdateSubscriptionResponse {
+    subscription: {
+        id: string;
+        status: string;
+        proration?: {
+            credited: number;
+            charged: number;
+            total: number;
+        };
+    };
+    upcomingInvoice?: {
+        amountDue: number;
+        dueDate: string;
+    };
+}
+
+/**
+ * Usage information for a feature
+ */
+export declare interface PortalUsageInfo {
+    consumed: number;
+    limit: number;
+    percentage: number;
+    resetDate?: string;
+}
+
+/**
+ * Input for previewing a plan change
+ */
+export declare interface PreviewChangeInput {
+    new_price_id: string;
+    effective_date?: ChangeEffectiveTiming;
+}
+
+/**
+ * Response from POST /subscriptions/:id/preview-change
+ */
+export declare interface PreviewChangeResponse {
+    current_plan: PlanInfo;
+    new_plan: PlanInfo;
+    proration: ProrationInfo;
+    change_type: ChangeType;
+    effective_date: string;
+    next_billing_date: string;
+    notes: string[];
+}
+
+export declare interface Price {
+    id: string;
+    amount: number;
+    currency: string;
+    interval?: string;
+    interval_count?: number;
+}
+
+export declare function PricingCard({ product, selectedInterval, currentSubscription, onSelectPlan, }: PricingCardProps): JSX.Element;
+
+export declare interface PricingCardProps {
+    product: PricingProduct;
+    selectedInterval: 'month' | 'year';
+    currentSubscription: PricingCurrentSubscription | null;
+    onSelectPlan: (priceId: string) => void;
+    theme?: 'light' | 'dark';
+}
+
+/**
+ * Current subscription info for pricing table
+ */
+export declare interface PricingCurrentSubscription {
+    id: string;
+    productId: string;
+    priceId: string;
+    status: 'active' | 'trialing' | 'past_due' | 'canceled';
+    currentPeriodEnd: string;
+    cancelAtPeriodEnd: boolean;
+}
+
+/**
+ * Feature in pricing table
+ */
+export declare interface PricingFeature {
+    id: string;
+    name: string;
+    title: string;
+    type: 'boolean_flag' | 'usage_quota' | 'numeric_limit';
+    properties: PricingFeatureProperties;
+}
+
+/**
+ * Feature properties for pricing table
+ */
+export declare interface PricingFeatureProperties {
+    limit?: number;
+    period?: 'month' | 'year';
+    unit?: string;
+}
+
+/**
+ * Price for a product
+ */
+export declare interface PricingPrice {
+    id: string;
+    amount: number;
+    currency: string;
+    interval: 'month' | 'year' | 'week' | 'day';
+    intervalCount: number;
+}
+
+/**
+ * Product in pricing table
+ */
+export declare interface PricingProduct {
+    id: string;
+    name: string;
+    description: string;
+    prices: PricingPrice[];
+    features: PricingFeature[];
+    isCurrentPlan: boolean;
+    trialDays: number;
+    highlighted?: boolean;
+}
+
+export declare function PricingTable({ planIds, showIntervalToggle, defaultInterval, onSelectPlan, theme, title, description, useCheckoutModal, onPlanChanged, customer: customerProp, }: PricingTableProps): JSX.Element;
+
+export declare interface PricingTableProps {
+    planIds?: string[];
+    showIntervalToggle?: boolean;
+    defaultInterval?: 'month' | 'year';
+    onSelectPlan?: (priceId: string) => void;
+    theme?: 'light' | 'dark';
+    title?: string;
+    description?: string;
+    /** Use the new iframe-based checkout modal instead of bottom sheet */
+    useCheckoutModal?: boolean;
+    /** Callback when plan is changed (for upgrade/downgrade flows) */
+    onPlanChanged?: (subscription: any) => void;
+    /** Customer information to prefill in checkout (overrides context) */
+    customer?: {
+        email?: string;
+        name?: string;
+    };
+}
+
+export declare interface Product {
+    id: string;
+    name: string;
+    description?: string;
+    features?: string[];
+    prices?: Price[];
+}
+
+export declare const Progress: React_2.ForwardRefExoticComponent<ProgressProps & React_2.RefAttributes<HTMLDivElement>>;
+
+declare interface ProgressProps extends React_2.HTMLAttributes<HTMLDivElement> {
+    value?: number;
+    max?: number;
+    indicatorClassName?: string;
+}
+
+/**
+ * Proration details
+ */
+export declare interface ProrationInfo {
+    unused_time_credit: number;
+    new_plan_charge: number;
+    immediate_payment: number;
+    credit_applied: number;
+    breakdown: string;
+}
+
+export declare const RadioGroup: React_2.ForwardRefExoticComponent<RadioGroupProps & React_2.RefAttributes<HTMLDivElement>>;
+
+export declare const RadioGroupItem: React_2.ForwardRefExoticComponent<RadioGroupItemProps & React_2.RefAttributes<HTMLInputElement>>;
+
+declare interface RadioGroupItemProps extends Omit<React_2.InputHTMLAttributes<HTMLInputElement>, 'type'> {
+    value: string;
+}
+
+declare interface RadioGroupProps extends Omit<React_2.HTMLAttributes<HTMLDivElement>, 'onChange'> {
+    value?: string;
+    defaultValue?: string;
+    onValueChange?: (value: string) => void;
+    name?: string;
+}
+
+/**
+ * Thrown when rate limit is exceeded (429)
+ */
+export declare class RateLimitError extends BillingOSError {
+    constructor(message?: string, data?: unknown);
+}
+
+/**
+ * Response for retrying an invoice
+ */
+export declare interface RetryInvoiceResponse {
+    success: boolean;
+    invoice: {
+        id: string;
+        status: 'paid' | 'open' | 'failed' | 'void';
+        amount: number;
+    };
+}
+
+export declare const ScrollArea: React_2.ForwardRefExoticComponent<ScrollAreaProps & React_2.RefAttributes<HTMLDivElement>>;
+
+declare interface ScrollAreaProps extends React_2.HTMLAttributes<HTMLDivElement> {
+    /**
+     * The orientation of the scrollable area
+     */
+    orientation?: 'vertical' | 'horizontal' | 'both';
+    /**
+     * Always show the custom scrollbar (instead of only on hover)
+     */
+    alwaysShowScrollbar?: boolean;
+}
+
+export declare const ScrollBar: React_2.ForwardRefExoticComponent<React_2.HTMLAttributes<HTMLDivElement> & {
+    orientation?: "vertical" | "horizontal";
+} & React_2.RefAttributes<HTMLDivElement>>;
+
+export declare const Select: React_2.ForwardRefExoticComponent<SelectProps & React_2.RefAttributes<HTMLSelectElement>>;
+
+export declare const SelectOption: React_2.ForwardRefExoticComponent<React_2.OptionHTMLAttributes<HTMLOptionElement> & React_2.RefAttributes<HTMLOptionElement>>;
+
+declare interface SelectProps extends React_2.SelectHTMLAttributes<HTMLSelectElement> {
+    onValueChange?: (value: string) => void;
+}
+
+export declare const Separator: React_2.ForwardRefExoticComponent<SeparatorProps & React_2.RefAttributes<HTMLDivElement>>;
+
+declare interface SeparatorProps extends React_2.HTMLAttributes<HTMLDivElement> {
+    orientation?: 'horizontal' | 'vertical';
+    decorative?: boolean;
+}
+
+/**
+ * Thrown when the server returns a 500 error
+ */
+export declare class ServerError extends BillingOSError {
+    constructor(message?: string, data?: unknown);
+}
+
+/**
+ * Hook for managing session tokens with auto-fetch and auto-refresh
+ */
+export declare interface SessionTokenData {
+    sessionToken: string;
+    expiresAt: string;
+}
+
+export declare function SettingsTab({ customer, onSave, isSaving, isLoading, className, }: SettingsTabProps): JSX.Element;
+
+declare interface SettingsTabProps {
+    customer: PortalCustomer;
+    onSave: (data: {
+        name?: string;
+        email?: string;
+        billingAddress?: PortalAddress;
+    }) => void;
+    isSaving?: boolean;
+    isLoading?: boolean;
+    className?: string;
+}
+
+/**
+ * Setup intent response for adding cards
+ */
+export declare interface SetupIntentResponse {
+    clientSecret: string;
+    stripePublishableKey: string;
+}
+
+export declare function Sheet({ open, onOpenChange, children }: SheetProps): JSX.Element;
+
+export declare const SheetClose: React_2.ForwardRefExoticComponent<React_2.ButtonHTMLAttributes<HTMLButtonElement> & React_2.RefAttributes<HTMLButtonElement>>;
+
+export declare const SheetContent: React_2.ForwardRefExoticComponent<SheetContentProps & React_2.RefAttributes<HTMLDivElement>>;
+
+declare interface SheetContentProps extends React_2.HTMLAttributes<HTMLDivElement>, VariantProps<typeof sheetVariants> {
+}
+
+export declare const SheetDescription: React_2.ForwardRefExoticComponent<React_2.HTMLAttributes<HTMLParagraphElement> & React_2.RefAttributes<HTMLParagraphElement>>;
+
+export declare const SheetFooter: {
+    ({ className, ...props }: React_2.HTMLAttributes<HTMLDivElement>): JSX.Element;
+    displayName: string;
+};
+
+export declare const SheetHeader: {
+    ({ className, ...props }: React_2.HTMLAttributes<HTMLDivElement>): JSX.Element;
+    displayName: string;
+};
+
+declare interface SheetProps {
+    open?: boolean;
+    onOpenChange?: (open: boolean) => void;
+    children: React_2.ReactNode;
+}
+
+export declare const SheetTitle: React_2.ForwardRefExoticComponent<React_2.HTMLAttributes<HTMLHeadingElement> & React_2.RefAttributes<HTMLHeadingElement>>;
+
+export declare const SheetTrigger: React_2.ForwardRefExoticComponent<SheetTriggerProps & React_2.RefAttributes<HTMLButtonElement>>;
+
+declare interface SheetTriggerProps extends React_2.ButtonHTMLAttributes<HTMLButtonElement> {
+    asChild?: boolean;
+}
+
+declare const sheetVariants: (props?: ({
+    side?: "left" | "right" | "bottom" | "top" | null | undefined;
+} & ClassProp) | undefined) => string;
+
+export declare function Skeleton({ className, ...props }: React.HTMLAttributes<HTMLDivElement>): JSX.Element;
+
+/**
+ * Subscription represents a customer subscription
+ */
+export declare interface Subscription {
+    id: string;
+    customer_id: string;
+    price_id: string;
+    status: SubscriptionStatus;
+    current_period_start: string;
+    current_period_end: string;
+    cancel_at_period_end: boolean;
+    trial_start?: string;
+    trial_end?: string;
+    canceled_at?: string;
+    metadata?: Record<string, string>;
+    created_at: string;
+    updated_at: string;
+}
+
+/**
+ * Query keys for subscription-related queries
+ */
+export declare const subscriptionKeys: {
+    all: readonly ["subscriptions"];
+    lists: () => readonly ["subscriptions", "list"];
+    list: (filters?: Record<string, unknown>) => readonly ["subscriptions", "list", Record<string, unknown> | undefined];
+    details: () => readonly ["subscriptions", "detail"];
+    detail: (id: string) => readonly ["subscriptions", "detail", string];
+    preview: (id: string, input: UpdateSubscriptionInput) => readonly ["subscriptions", "preview", string, UpdateSubscriptionInput];
+};
+
+/**
+ * Price preview for subscription changes
+ */
+export declare interface SubscriptionPreview {
+    proration_amount: number;
+    next_invoice_amount: number;
+    next_invoice_date: string;
+}
+
+/**
+ * Subscription status
+ */
+export declare type SubscriptionStatus = 'active' | 'canceled' | 'incomplete' | 'incomplete_expired' | 'past_due' | 'trialing' | 'unpaid';
+
+export declare function SubscriptionTab({ subscription, onChangePlan, onCancelSubscription, onReactivate, onAddPaymentMethod, isLoading, className, }: SubscriptionTabProps): JSX.Element;
+
+declare interface SubscriptionTabProps {
+    subscription: PortalSubscription | null;
+    availablePlans: PortalAvailablePlan[];
+    onChangePlan: () => void;
+    onCancelSubscription: () => void;
+    onReactivate: () => void;
+    onAddPaymentMethod: () => void;
+    isLoading?: boolean;
+    className?: string;
+}
+
+/**
+ * Suggested plan for upgrade
+ */
+export declare interface SuggestedPlan {
+    id: string;
+    priceId: string;
+    name: string;
+    price: {
+        amount: number;
+        currency: string;
+        interval: string;
+    };
+    highlights: string[];
+}
+
+export declare const Tabs: React_2.ForwardRefExoticComponent<TabsProps & React_2.RefAttributes<HTMLDivElement>>;
+
+export declare const TabsContent: React_2.ForwardRefExoticComponent<TabsContentProps & React_2.RefAttributes<HTMLDivElement>>;
+
+declare interface TabsContentProps extends React_2.HTMLAttributes<HTMLDivElement> {
+    value: string;
+}
+
+export declare const TabsList: React_2.ForwardRefExoticComponent<React_2.HTMLAttributes<HTMLDivElement> & React_2.RefAttributes<HTMLDivElement>>;
+
+declare interface TabsProps extends React_2.HTMLAttributes<HTMLDivElement> {
+    value?: string;
+    defaultValue?: string;
+    onValueChange?: (value: string) => void;
+}
+
+export declare const TabsTrigger: React_2.ForwardRefExoticComponent<TabsTriggerProps & React_2.RefAttributes<HTMLButtonElement>>;
+
+declare interface TabsTriggerProps extends React_2.ButtonHTMLAttributes<HTMLButtonElement> {
+    value: string;
+}
+
+export declare const Textarea: React_2.ForwardRefExoticComponent<Omit<React_2.DetailedHTMLProps<React_2.TextareaHTMLAttributes<HTMLTextAreaElement>, HTMLTextAreaElement>, "ref"> & React_2.RefAttributes<HTMLTextAreaElement>>;
+
+export declare function ToastNudge({ trigger, onUpgrade, onDismiss, }: ToastNudgeProps): JSX.Element;
+
+export declare interface ToastNudgeProps {
+    trigger: NudgeTrigger;
+    onUpgrade: () => void;
+    onDismiss: () => void;
+    theme?: 'light' | 'dark';
+}
+
+/**
+ * Thrown when the API request fails due to authentication issues (401)
+ */
+export declare class UnauthorizedError extends BillingOSError {
+    constructor(message?: string, data?: unknown);
+}
+
+/**
+ * Input for updating customer billing
+ */
+export declare interface UpdateCustomerBillingInput {
+    name?: string;
+    email?: string;
+    billingAddress?: PortalAddress;
+}
+
+/**
+ * Input for updating a customer
+ */
+export declare interface UpdateCustomerInput {
+    email?: string;
+    name?: string;
+    metadata?: Record<string, string>;
+}
+
+/**
+ * Input for updating a subscription
+ */
+export declare interface UpdateSubscriptionInput {
+    price_id?: string;
+    cancel_at_period_end?: boolean;
+    metadata?: Record<string, string>;
+}
+
+export declare function UpgradeNudge({ trigger, style, autoDismiss, onUpgrade, onDismiss, theme, }: UpgradeNudgeProps): JSX.Element | null;
+
+export declare interface UpgradeNudgeProps {
+    /**
+     * Nudge trigger data (from API or usage check)
+     */
+    trigger: NudgeTrigger;
+    /**
+     * Display style
+     * - 'banner': Top banner (non-intrusive)
+     * - 'toast': Toast notification (bottom-right)
+     * - 'modal': Modal dialog (more prominent)
+     */
+    style?: 'banner' | 'toast' | 'modal';
+    /**
+     * Auto-dismiss after N milliseconds (0 = no auto-dismiss)
+     */
+    autoDismiss?: number;
+    /**
+     * Callback when user clicks upgrade
+     */
+    onUpgrade?: (priceId: string) => void;
+    /**
+     * Callback when user dismisses nudge
+     */
+    onDismiss?: () => void;
+    /**
+     * Optional: Custom theme
+     */
+    theme?: 'light' | 'dark';
+}
+
+/**
+ * Component that prompts users to upgrade when they hit limits or access denied features
+ *
+ * @example
+ * ```tsx
+ * <UpgradePrompt
+ *   feature="Advanced Analytics"
+ *   description="Upgrade to Pro to access advanced analytics and reporting"
+ * />
+ * ```
+ */
+export declare function UpgradePrompt({ feature, title, description, isQuotaExceeded, usage, limit, className, onUpgradeClick, }: UpgradePromptProps): JSX.Element;
+
+export declare interface UpgradePromptProps {
+    /**
+     * Feature that requires upgrade
+     */
+    feature?: string;
+    /**
+     * Title text
+     */
+    title?: string;
+    /**
+     * Description text
+     */
+    description?: string;
+    /**
+     * Whether it's a quota exceeded prompt
+     */
+    isQuotaExceeded?: boolean;
+    /**
+     * Current usage (for quota exceeded)
+     */
+    usage?: number;
+    /**
+     * Usage limit (for quota exceeded)
+     */
+    limit?: number;
+    /**
+     * Custom className for styling
+     */
+    className?: string;
+    /**
+     * Click handler for upgrade button
+     */
+    onUpgradeClick?: () => void;
+}
+
+export declare function UsageBar({ title, usage, unit, className }: UsageBarProps): JSX.Element;
+
+declare interface UsageBarProps {
+    title: string;
+    usage: PortalUsageInfo;
+    unit?: string;
+    className?: string;
+}
+
+/**
+ * Response from GET /sdk/usage/check
+ */
+export declare interface UsageCheckResponse {
+    shouldShowNudge: boolean;
+    trigger?: NudgeTrigger;
+}
+
+/**
+ * Component to display usage metrics for features
+ *
+ * @example
+ * ```tsx
+ * // Show all usage metrics
+ * <UsageDisplay />
+ *
+ * // Show specific feature usage
+ * <UsageDisplay featureKey="api_calls" />
+ * ```
+ */
+export declare function UsageDisplay({ featureKey, title, showProgress, showResetTimer, className, }: UsageDisplayProps): JSX.Element;
+
+export declare interface UsageDisplayProps {
+    /**
+     * Optional feature key to show usage for specific feature
+     */
+    featureKey?: string;
+    /**
+     * Custom title
+     */
+    title?: string;
+    /**
+     * Whether to show a progress bar
+     */
+    showProgress?: boolean;
+    /**
+     * Whether to show reset timer
+     */
+    showResetTimer?: boolean;
+    /**
+     * Custom className for styling
+     */
+    className?: string;
+}
+
+/**
+ * Usage event for tracking
+ */
+export declare interface UsageEvent {
+    customer_id?: string;
+    feature_key: string;
+    quantity: number;
+    timestamp?: string;
+    idempotency_key?: string;
+    metadata?: Record<string, string>;
+}
+
+/**
+ * Usage metric
+ */
+export declare interface UsageMetric {
+    feature_key: string;
+    feature_title: string;
+    product_name: string;
+    consumed: number;
+    limit: number;
+    remaining: number;
+    percentage_used: number;
+    period_start: string;
+    period_end: string;
+    resets_in_days: number;
+}
+
+/**
+ * Usage metrics response
+ */
+export declare interface UsageMetrics {
+    feature_key: string;
+    current_usage: number;
+    limit?: number;
+    period_start: string;
+    period_end: string;
+}
+
+/**
+ * Add a payment method
+ */
+export declare function useAddPaymentMethod(options?: Omit<UseMutationOptions<AddPaymentMethodResponse, Error, AddPaymentMethodInput>, 'mutationFn'>): UseMutationResult<AddPaymentMethodResponse, Error, AddPaymentMethodInput, unknown>;
+
+/**
+ * Fetch available plans for upgrade/downgrade
+ *
+ * @param subscriptionId - Subscription ID
+ * @param options - React Query options
+ *
+ * @example
+ * ```tsx
+ * function AvailablePlans({ subscriptionId }: { subscriptionId: string }) {
+ *   const { data, isLoading } = useAvailablePlans(subscriptionId)
+ *
+ *   if (isLoading) return <div>Loading plans...</div>
+ *
+ *   return (
+ *     <div>
+ *       <h3>Upgrades:</h3>
+ *       {data?.available_upgrades.map(plan => (
+ *         <div key={plan.price_id}>{plan.product_name}</div>
+ *       ))}
+ *     </div>
+ *   )
+ * }
+ * ```
+ */
+export declare function useAvailablePlans(subscriptionId: string, options?: Omit<UseQueryOptions<AvailablePlansResponse>, 'queryKey' | 'queryFn'>): UseQueryResult<AvailablePlansResponse, Error>;
+
+/**
+ * Hook to access the BillingOS context
+ *
+ * Must be used within a BillingOSProvider.
+ *
+ * @throws Error if used outside of BillingOSProvider
+ *
+ * @example
+ * ```tsx
+ * function MyComponent() {
+ *   const { client, customerId } = useBillingOS()
+ *
+ *   // Use client to make API calls
+ *   const subscription = await client.getSubscription(id)
+ *
+ *   return <div>Customer: {customerId}</div>
+ * }
+ * ```
+ */
+export declare function useBillingOS(): BillingOSContextValue;
+
+export { useBillingOSQueryClient }
+
+/**
+ * Cancel subscription with feedback
+ */
+export declare function useCancelPortalSubscription(subscriptionId: string, options?: Omit<UseMutationOptions<PortalCancelSubscriptionResponse, Error, PortalCancelSubscriptionInput>, 'mutationFn'>): UseMutationResult<PortalCancelSubscriptionResponse, Error, PortalCancelSubscriptionInput, unknown>;
+
+/**
+ * Cancel a subscription
+ *
+ * @param subscriptionId - Subscription ID to cancel
+ * @param options - React Query mutation options
+ *
+ * @example
+ * ```tsx
+ * function CancelButton({ subscriptionId }: { subscriptionId: string }) {
+ *   const cancelSubscription = useCancelSubscription(subscriptionId, {
+ *     onSuccess: () => {
+ *       alert('Subscription cancelled')
+ *     }
+ *   })
+ *
+ *   const handleCancel = (immediately: boolean) => {
+ *     if (confirm('Are you sure you want to cancel?')) {
+ *       cancelSubscription.mutate({ immediately })
+ *     }
+ *   }
+ *
+ *   return (
+ *     <div>
+ *       <button onClick={() => handleCancel(false)}>
+ *         Cancel at period end
+ *       </button>
+ *       <button onClick={() => handleCancel(true)}>
+ *         Cancel immediately
+ *       </button>
+ *     </div>
+ *   )
+ * }
+ * ```
+ */
+export declare function useCancelSubscription(subscriptionId: string, options?: Omit<UseMutationOptions<Subscription, Error, {
+    immediately?: boolean;
+}>, 'mutationFn'>): UseMutationResult<Subscription, Error, {
+immediately?: boolean;
+}, unknown>;
+
+/**
+ * Execute a plan change (upgrade/downgrade)
+ *
+ * @param options - React Query mutation options
+ *
+ * @example
+ * ```tsx
+ * function ChangePlanButton({ subscriptionId }: { subscriptionId: string }) {
+ *   const changePlan = useChangePlan({
+ *     onSuccess: (response) => {
+ *       console.log('Plan changed:', response.subscription.id)
+ *     }
+ *   })
+ *
+ *   const handleChange = () => {
+ *     changePlan.mutate({
+ *       subscriptionId,
+ *       input: {
+ *         new_price_id: 'price_456',
+ *         confirm_amount: 1999
+ *       }
+ *     })
+ *   }
+ *
+ *   return (
+ *     <button onClick={handleChange} disabled={changePlan.isPending}>
+ *       {changePlan.isPending ? 'Changing...' : 'Change Plan'}
+ *     </button>
+ *   )
+ * }
+ * ```
+ */
+export declare function useChangePlan(options?: Omit<UseMutationOptions<ChangePlanResponse, Error, {
+    subscriptionId: string;
+    input: ChangePlanInput;
+}>, 'mutationFn'>): UseMutationResult<ChangePlanResponse, Error, {
+subscriptionId: string;
+input: ChangePlanInput;
+}, unknown>;
+
+/**
+ * Check if a customer has access to a specific feature
+ *
+ * @param customerId - Customer ID to check
+ * @param featureKey - Feature key to check access for
+ * @param options - React Query options
+ *
+ * @example
+ * ```tsx
+ * function FeatureGate({ children }: { children: React.ReactNode }) {
+ *   const { data: entitlement, isLoading } = useCheckEntitlement(
+ *     'cus_123',
+ *     'advanced_analytics'
+ *   )
+ *
+ *   if (isLoading) return <div>Checking access...</div>
+ *   if (!entitlement?.has_access) {
+ *     return <UpgradePrompt feature="advanced_analytics" />
+ *   }
+ *
+ *   return <>{children}</>
+ * }
+ * ```
+ */
+export declare function useCheckEntitlement(customerId: string, featureKey: string, options?: Omit<UseQueryOptions<Entitlement>, 'queryKey' | 'queryFn'>): UseQueryResult<Entitlement, Error>;
+
+/**
+ * Hook for programmatically opening checkout
+ */
+export declare function useCheckout(): {
+    openCheckout: (options: Omit<CheckoutOpenOptions, "sessionToken" | "apiUrl">) => Promise<CheckoutResult>;
+    closeCheckout: () => void;
+    isLoading: boolean;
+    error: Error | null;
+};
+
+/**
+ * Hook to confirm a checkout after payment
+ */
+export declare function useConfirmCheckout(options?: {
+    onSuccess?: (data: ConfirmCheckoutResponse) => void;
+    onError?: (error: Error) => void;
+}): UseMutationResult<ConfirmCheckoutResponse, Error, {
+clientSecret: string;
+paymentMethodId: string;
+}, unknown>;
+
+/**
+ * Hook to create a checkout session
+ */
+export declare function useCreateCheckout(input: CreateCheckoutInput | null, options?: {
+    enabled?: boolean;
+    onSuccess?: (data: CreateCheckoutResponse) => void;
+    onError?: (error: Error) => void;
+}): UseQueryResult<CheckoutSession, Error>;
+
+/**
+ * Create a new subscription
+ *
+ * @param options - React Query mutation options
+ *
+ * @example
+ * ```tsx
+ * function CreateSubscriptionButton() {
+ *   const createSubscription = useCreateSubscription({
+ *     onSuccess: (subscription) => {
+ *       console.log('Subscription created:', subscription.id)
+ *       // Redirect to success page
+ *     },
+ *     onError: (error) => {
+ *       console.error('Failed to create subscription:', error)
+ *     }
+ *   })
+ *
+ *   const handleClick = () => {
+ *     createSubscription.mutate({
+ *       customer_id: 'cus_123',
+ *       price_id: 'price_456',
+ *       trial_days: 14
+ *     })
+ *   }
+ *
+ *   return (
+ *     <button
+ *       onClick={handleClick}
+ *       disabled={createSubscription.isPending}
+ *     >
+ *       {createSubscription.isPending ? 'Creating...' : 'Subscribe'}
+ *     </button>
+ *   )
+ * }
+ * ```
+ */
+export declare function useCreateSubscription(options?: Omit<UseMutationOptions<Subscription, Error, CreateSubscriptionInput>, 'mutationFn'>): UseMutationResult<Subscription, Error, CreateSubscriptionInput, unknown>;
+
+/**
+ * Get all entitlements for a customer
+ *
+ * @param customerId - Customer ID
+ * @param options - React Query options
+ *
+ * @example
+ * ```tsx
+ * function EntitlementsList({ customerId }: { customerId: string }) {
+ *   const { data: entitlements, isLoading } = useEntitlements(customerId)
+ *
+ *   if (isLoading) return <div>Loading...</div>
+ *
+ *   return (
+ *     <ul>
+ *       {entitlements?.map(entitlement => (
+ *         <li key={entitlement.feature_key}>
+ *           {entitlement.feature_key}: {entitlement.has_access ? '✓' : '✗'}
+ *           {entitlement.limit && ` (${entitlement.usage}/${entitlement.limit})`}
+ *         </li>
+ *       ))}
+ *     </ul>
+ *   )
+ * }
+ * ```
+ */
+export declare function useEntitlements(customerId: string, options?: Omit<UseQueryOptions<Entitlement[]>, 'queryKey' | 'queryFn'>): UseQueryResult<Entitlement[], Error>;
+
+/**
+ * Hook to check if user has access to a feature
+ */
+export declare function useFeature(featureKey: string, options?: {
+    refetchInterval?: number;
+    enabled?: boolean;
+}): UseQueryResult<FeatureAccess, Error>;
+
+/**
+ * Hook to get all feature entitlements for the current user
+ */
+export declare function useFeatureEntitlements(): UseQueryResult<    {
+entitlements: FeatureEntitlement[];
+}, Error>;
+
+/**
+ * Hook that combines feature access check and tracks when access is denied
+ */
+export declare function useFeatureGate(featureKey: string, options?: {
+    onAccessDenied?: () => void;
+    onQuotaExceeded?: (usage: number, limit: number) => void;
+}): {
+    hasAccess: boolean;
+    isQuotaExceeded: boolean;
+    usage: number;
+    limit: number;
+    remaining: number;
+    data: FeatureAccess;
+    error: Error;
+    isError: true;
+    isPending: false;
+    isLoading: false;
+    isLoadingError: false;
+    isRefetchError: true;
+    isSuccess: false;
+    isPlaceholderData: false;
+    status: "error";
+    dataUpdatedAt: number;
+    errorUpdatedAt: number;
+    failureCount: number;
+    failureReason: Error | null;
+    errorUpdateCount: number;
+    isFetched: boolean;
+    isFetchedAfterMount: boolean;
+    isFetching: boolean;
+    isInitialLoading: boolean;
+    isPaused: boolean;
+    isRefetching: boolean;
+    isStale: boolean;
+    isEnabled: boolean;
+    refetch: (options?: RefetchOptions) => Promise<QueryObserverResult<FeatureAccess, Error>>;
+    fetchStatus: FetchStatus;
+    promise: Promise<FeatureAccess>;
+} | {
+    hasAccess: boolean;
+    isQuotaExceeded: boolean;
+    usage: number;
+    limit: number;
+    remaining: number;
+    data: FeatureAccess;
+    error: null;
+    isError: false;
+    isPending: false;
+    isLoading: false;
+    isLoadingError: false;
+    isRefetchError: false;
+    isSuccess: true;
+    isPlaceholderData: false;
+    status: "success";
+    dataUpdatedAt: number;
+    errorUpdatedAt: number;
+    failureCount: number;
+    failureReason: Error | null;
+    errorUpdateCount: number;
+    isFetched: boolean;
+    isFetchedAfterMount: boolean;
+    isFetching: boolean;
+    isInitialLoading: boolean;
+    isPaused: boolean;
+    isRefetching: boolean;
+    isStale: boolean;
+    isEnabled: boolean;
+    refetch: (options?: RefetchOptions) => Promise<QueryObserverResult<FeatureAccess, Error>>;
+    fetchStatus: FetchStatus;
+    promise: Promise<FeatureAccess>;
+} | {
+    hasAccess: boolean;
+    isQuotaExceeded: boolean;
+    usage: number;
+    limit: number;
+    remaining: number;
+    data: undefined;
+    error: Error;
+    isError: true;
+    isPending: false;
+    isLoading: false;
+    isLoadingError: true;
+    isRefetchError: false;
+    isSuccess: false;
+    isPlaceholderData: false;
+    status: "error";
+    dataUpdatedAt: number;
+    errorUpdatedAt: number;
+    failureCount: number;
+    failureReason: Error | null;
+    errorUpdateCount: number;
+    isFetched: boolean;
+    isFetchedAfterMount: boolean;
+    isFetching: boolean;
+    isInitialLoading: boolean;
+    isPaused: boolean;
+    isRefetching: boolean;
+    isStale: boolean;
+    isEnabled: boolean;
+    refetch: (options?: RefetchOptions) => Promise<QueryObserverResult<FeatureAccess, Error>>;
+    fetchStatus: FetchStatus;
+    promise: Promise<FeatureAccess>;
+} | {
+    hasAccess: boolean;
+    isQuotaExceeded: boolean;
+    usage: number;
+    limit: number;
+    remaining: number;
+    data: undefined;
+    error: null;
+    isError: false;
+    isPending: true;
+    isLoading: true;
+    isLoadingError: false;
+    isRefetchError: false;
+    isSuccess: false;
+    isPlaceholderData: false;
+    status: "pending";
+    dataUpdatedAt: number;
+    errorUpdatedAt: number;
+    failureCount: number;
+    failureReason: Error | null;
+    errorUpdateCount: number;
+    isFetched: boolean;
+    isFetchedAfterMount: boolean;
+    isFetching: boolean;
+    isInitialLoading: boolean;
+    isPaused: boolean;
+    isRefetching: boolean;
+    isStale: boolean;
+    isEnabled: boolean;
+    refetch: (options?: RefetchOptions) => Promise<QueryObserverResult<FeatureAccess, Error>>;
+    fetchStatus: FetchStatus;
+    promise: Promise<FeatureAccess>;
+} | {
+    hasAccess: boolean;
+    isQuotaExceeded: boolean;
+    usage: number;
+    limit: number;
+    remaining: number;
+    data: undefined;
+    error: null;
+    isError: false;
+    isPending: true;
+    isLoadingError: false;
+    isRefetchError: false;
+    isSuccess: false;
+    isPlaceholderData: false;
+    status: "pending";
+    dataUpdatedAt: number;
+    errorUpdatedAt: number;
+    failureCount: number;
+    failureReason: Error | null;
+    errorUpdateCount: number;
+    isFetched: boolean;
+    isFetchedAfterMount: boolean;
+    isFetching: boolean;
+    isLoading: boolean;
+    isInitialLoading: boolean;
+    isPaused: boolean;
+    isRefetching: boolean;
+    isStale: boolean;
+    isEnabled: boolean;
+    refetch: (options?: RefetchOptions) => Promise<QueryObserverResult<FeatureAccess, Error>>;
+    fetchStatus: FetchStatus;
+    promise: Promise<FeatureAccess>;
+} | {
+    hasAccess: boolean;
+    isQuotaExceeded: boolean;
+    usage: number;
+    limit: number;
+    remaining: number;
+    data: FeatureAccess;
+    isError: false;
+    error: null;
+    isPending: false;
+    isLoading: false;
+    isLoadingError: false;
+    isRefetchError: false;
+    isSuccess: true;
+    isPlaceholderData: true;
+    status: "success";
+    dataUpdatedAt: number;
+    errorUpdatedAt: number;
+    failureCount: number;
+    failureReason: Error | null;
+    errorUpdateCount: number;
+    isFetched: boolean;
+    isFetchedAfterMount: boolean;
+    isFetching: boolean;
+    isInitialLoading: boolean;
+    isPaused: boolean;
+    isRefetching: boolean;
+    isStale: boolean;
+    isEnabled: boolean;
+    refetch: (options?: RefetchOptions) => Promise<QueryObserverResult<FeatureAccess, Error>>;
+    fetchStatus: FetchStatus;
+    promise: Promise<FeatureAccess>;
+};
+
+/**
+ * Simplified hook to check if a customer has access to a feature
+ * Returns a boolean directly instead of the full Entitlement object
+ *
+ * @param customerId - Customer ID to check
+ * @param featureKey - Feature key to check access for
+ * @param options - React Query options
+ *
+ * @example
+ * ```tsx
+ * function PremiumFeature() {
+ *   const hasAccess = useHasFeature('cus_123', 'premium_features')
+ *
+ *   if (!hasAccess) {
+ *     return <div>Upgrade to access this feature</div>
+ *   }
+ *
+ *   return <div>Premium feature content here</div>
+ * }
+ * ```
+ */
+export declare function useHasFeature(customerId: string, featureKey: string, options?: Omit<UseQueryOptions<Entitlement>, 'queryKey' | 'queryFn'>): boolean;
+
+/**
+ * Check if a customer is approaching their usage limit
+ *
+ * @param customerId - Customer ID
+ * @param featureKey - Feature key
+ * @param threshold - Threshold percentage (0-100) to warn at (default: 80)
+ * @param options - React Query options
+ * @returns Boolean indicating if customer is approaching limit
+ *
+ * @example
+ * ```tsx
+ * function UsageWarning({ customerId }: { customerId: string }) {
+ *   const isApproachingLimit = useIsApproachingLimit(
+ *     customerId,
+ *     'api_calls',
+ *     80 // Warn at 80%
+ *   )
+ *
+ *   if (!isApproachingLimit) return null
+ *
+ *   return (
+ *     <Alert variant="warning">
+ *       You're approaching your API call limit. Upgrade to increase your quota.
+ *     </Alert>
+ *   )
+ * }
+ * ```
+ */
+export declare function useIsApproachingLimit(customerId: string, featureKey: string, threshold?: number, options?: Omit<UseQueryOptions<UsageMetrics>, 'queryKey' | 'queryFn'>): boolean;
+
+/**
+ * Fetch all portal data for the current customer
+ * Returns subscription, invoices, payment methods, customer info, and available plans
+ */
+export declare function usePortalData(options?: Omit<UseQueryOptions<CustomerPortalData>, 'queryKey' | 'queryFn'>): UseQueryResult<CustomerPortalData, Error>;
+
+/**
+ * Preview a plan change with proration details
+ *
+ * @param options - React Query mutation options
+ *
+ * @example
+ * ```tsx
+ * function PlanChangePreview({ subscriptionId }: { subscriptionId: string }) {
+ *   const previewChange = usePreviewPlanChange()
+ *
+ *   const handlePreview = async (newPriceId: string) => {
+ *     const preview = await previewChange.mutateAsync({
+ *       subscriptionId,
+ *       input: { new_price_id: newPriceId }
+ *     })
+ *     console.log('Proration:', preview.proration.immediate_payment)
+ *   }
+ *
+ *   return <button onClick={() => handlePreview('price_123')}>Preview</button>
+ * }
+ * ```
+ */
+export declare function usePreviewPlanChange(options?: Omit<UseMutationOptions<PreviewChangeResponse, Error, {
+    subscriptionId: string;
+    input: PreviewChangeInput;
+}>, 'mutationFn'>): UseMutationResult<PreviewChangeResponse, Error, {
+subscriptionId: string;
+input: PreviewChangeInput;
+}, unknown>;
+
+/**
+ * Hook to fetch products for pricing table
+ */
+export declare function usePricingTableProducts(options?: UseProductsOptions): UseQueryResult<GetProductsResponse, Error>;
+
+/**
+ * Hook to fetch products for pricing table
+ */
+export declare function useProducts(): UseQueryResult<    {
+products: Product[];
+}, Error>;
+
+export declare interface UseProductsOptions {
+    /**
+     * Optional array of plan IDs to filter
+     */
+    planIds?: string[];
+    /**
+     * Whether to enable the query
+     */
+    enabled?: boolean;
+}
+
+/**
+ * Reactivate a canceled subscription
+ */
+export declare function useReactivatePortalSubscription(subscriptionId: string, options?: Omit<UseMutationOptions<void, Error, void>, 'mutationFn'>): UseMutationResult<void, Error, void, unknown>;
+
+/**
+ * Reactivate a canceled subscription
+ *
+ * @param subscriptionId - Subscription ID to reactivate
+ * @param options - React Query mutation options
+ *
+ * @example
+ * ```tsx
+ * function ReactivateButton({ subscriptionId }: { subscriptionId: string }) {
+ *   const reactivateSubscription = useReactivateSubscription(subscriptionId)
+ *
+ *   return (
+ *     <button
+ *       onClick={() => reactivateSubscription.mutate()}
+ *       disabled={reactivateSubscription.isPending}
+ *     >
+ *       Reactivate Subscription
+ *     </button>
+ *   )
+ * }
+ * ```
+ */
+export declare function useReactivateSubscription(subscriptionId: string, options?: Omit<UseMutationOptions<Subscription, Error, void>, 'mutationFn'>): UseMutationResult<Subscription, Error, void, unknown>;
+
+/**
+ * Remove a payment method
+ */
+export declare function useRemovePaymentMethod(options?: Omit<UseMutationOptions<void, Error, string>, 'mutationFn'>): UseMutationResult<void, Error, string, unknown>;
+
+/**
+ * Retry a failed invoice
+ */
+export declare function useRetryInvoice(options?: Omit<UseMutationOptions<RetryInvoiceResponse, Error, {
+    invoiceId: string;
+    paymentMethodId?: string;
+}>, 'mutationFn'>): UseMutationResult<RetryInvoiceResponse, Error, {
+invoiceId: string;
+paymentMethodId?: string;
+}, unknown>;
+
+/**
+ * Hook to manage session tokens with automatic fetching and refreshing
+ *
+ * @example
+ * // Auto-fetch from endpoint
+ * const { token, isLoading } = useSessionToken({
+ *   tokenUrl: '/api/billingos-session',
+ * });
+ *
+ * @example
+ * // Manual token
+ * const { token } = useSessionToken({
+ *   token: 'bos_session_abc123...',
+ * });
+ */
+export declare function useSessionToken(options?: UseSessionTokenOptions): UseSessionTokenReturn;
+
+export declare interface UseSessionTokenOptions {
+    /** URL to fetch session token from (e.g., /api/billingos-session) */
+    tokenUrl?: string;
+    /** Manually provided session token */
+    token?: string;
+    /** How many seconds before expiry to refresh (default: 300 = 5 minutes) */
+    refreshBeforeExpiry?: number;
+    /** Enable auto-refresh (default: true) */
+    autoRefresh?: boolean;
+    /** Callback when token is refreshed */
+    onTokenRefresh?: (token: string) => void;
+    /** Callback when token fetch fails */
+    onError?: (error: Error) => void;
+}
+
+export declare interface UseSessionTokenReturn {
+    /** Current session token */
+    token: string | null;
+    /** When the token expires */
+    expiresAt: Date | null;
+    /** Whether the token is currently being fetched */
+    isLoading: boolean;
+    /** Any error that occurred */
+    error: Error | null;
+    /** Manually refresh the token */
+    refresh: () => Promise<void>;
+    /** Whether the token is valid (not expired) */
+    isValid: boolean;
+}
+
+/**
+ * Set default payment method
+ */
+export declare function useSetDefaultPaymentMethod(options?: Omit<UseMutationOptions<void, Error, string>, 'mutationFn'>): UseMutationResult<void, Error, string, unknown>;
+
+/**
+ * Get setup intent for adding a new payment method
+ */
+export declare function useSetupIntent(options?: Omit<UseQueryOptions<SetupIntentResponse>, 'queryKey' | 'queryFn'>): UseQueryResult<SetupIntentResponse, Error>;
+
+/**
+ * Fetch a single subscription by ID
+ *
+ * @param id - Subscription ID
+ * @param options - React Query options
+ *
+ * @example
+ * ```tsx
+ * function SubscriptionDetails({ id }: { id: string }) {
+ *   const { data: subscription, isLoading, error } = useSubscription(id)
+ *
+ *   if (isLoading) return <div>Loading...</div>
+ *   if (error) return <div>Error: {error.message}</div>
+ *
+ *   return (
+ *     <div>
+ *       <h1>Subscription Status: {subscription.status}</h1>
+ *       <p>Next billing: {subscription.current_period_end}</p>
+ *     </div>
+ *   )
+ * }
+ * ```
+ */
+export declare function useSubscription(id: string, options?: Omit<UseQueryOptions<Subscription>, 'queryKey' | 'queryFn'>): UseQueryResult<Subscription, Error>;
+
+/**
+ * Preview subscription changes before applying them
+ *
+ * @param subscriptionId - Subscription ID
+ * @param input - Proposed changes
+ * @param options - React Query options
+ *
+ * @example
+ * ```tsx
+ * function UpgradePreview({ subscriptionId }: { subscriptionId: string }) {
+ *   const { data: preview, isLoading } = useSubscriptionPreview(
+ *     subscriptionId,
+ *     { price_id: 'price_pro_plan' }
+ *   )
+ *
+ *   if (isLoading) return <div>Calculating...</div>
+ *
+ *   return (
+ *     <div>
+ *       <p>Proration: ${preview?.proration_amount / 100}</p>
+ *       <p>Next invoice: ${preview?.next_invoice_amount / 100}</p>
+ *       <p>Billing date: {preview?.next_invoice_date}</p>
+ *     </div>
+ *   )
+ * }
+ * ```
+ */
+export declare function useSubscriptionPreview(subscriptionId: string, input: UpdateSubscriptionInput, options?: Omit<UseQueryOptions<SubscriptionPreview>, 'queryKey' | 'queryFn'>): UseQueryResult<SubscriptionPreview, Error>;
+
+/**
+ * Fetch a list of subscriptions (paginated)
+ *
+ * @param params - Query parameters (customer_id, pagination)
+ * @param options - React Query options
+ *
+ * @example
+ * ```tsx
+ * function SubscriptionsList() {
+ *   const { data, isLoading } = useSubscriptions({
+ *     customer_id: 'cus_123',
+ *     page: 1,
+ *     page_size: 10
+ *   })
+ *
+ *   if (isLoading) return <div>Loading...</div>
+ *
+ *   return (
+ *     <div>
+ *       {data?.data.map(subscription => (
+ *         <SubscriptionCard key={subscription.id} subscription={subscription} />
+ *       ))}
+ *       <p>Total: {data?.meta.total}</p>
+ *     </div>
+ *   )
+ * }
+ * ```
+ */
+export declare function useSubscriptions(params?: {
+    customer_id?: string;
+    page?: number;
+    page_size?: number;
+}, options?: Omit<UseQueryOptions<PaginatedResponse<Subscription>>, 'queryKey' | 'queryFn'>): UseQueryResult<PaginatedResponse<Subscription>, Error>;
+
+/**
+ * Hook to track usage for a feature
+ */
+export declare function useTrackUsage(): UseMutationResult<unknown, Error, {
+featureKey: string;
+quantity: number;
+metadata?: Record<string, any>;
+}, unknown>;
+
+/**
+ * Update customer billing information
+ */
+export declare function useUpdateCustomerBilling(options?: Omit<UseMutationOptions<CustomerBillingInfo, Error, UpdateCustomerBillingInput>, 'mutationFn'>): UseMutationResult<CustomerBillingInfo, Error, UpdateCustomerBillingInput, unknown>;
+
+/**
+ * Update subscription (upgrade/downgrade)
+ */
+export declare function useUpdatePortalSubscription(subscriptionId: string, options?: Omit<UseMutationOptions<PortalUpdateSubscriptionResponse, Error, PortalUpdateSubscriptionInput>, 'mutationFn'>): UseMutationResult<PortalUpdateSubscriptionResponse, Error, PortalUpdateSubscriptionInput, unknown>;
+
+/**
+ * Update an existing subscription
+ *
+ * @param subscriptionId - Subscription ID to update
+ * @param options - React Query mutation options
+ *
+ * @example
+ * ```tsx
+ * function UpgradeButton({ subscriptionId }: { subscriptionId: string }) {
+ *   const updateSubscription = useUpdateSubscription(subscriptionId, {
+ *     onSuccess: () => {
+ *       console.log('Subscription updated!')
+ *     }
+ *   })
+ *
+ *   const handleUpgrade = () => {
+ *     updateSubscription.mutate({
+ *       price_id: 'price_pro_plan'
+ *     })
+ *   }
+ *
+ *   return (
+ *     <button onClick={handleUpgrade} disabled={updateSubscription.isPending}>
+ *       Upgrade to Pro
+ *     </button>
+ *   )
+ * }
+ * ```
+ */
+export declare function useUpdateSubscription(subscriptionId: string, options?: Omit<UseMutationOptions<Subscription, Error, UpdateSubscriptionInput>, 'mutationFn'>): UseMutationResult<Subscription, Error, UpdateSubscriptionInput, unknown>;
+
+/**
+ * Hook to check usage and get nudge trigger
+ */
+export declare function useUsageCheck(options?: UseUsageCheckOptions): UseQueryResult<UsageCheckResponse, Error>;
+
+export declare interface UseUsageCheckOptions {
+    /**
+     * Whether to enable the query
+     */
+    enabled?: boolean;
+    /**
+     * Refetch interval in milliseconds (0 = no auto refetch)
+     */
+    refetchInterval?: number;
+}
+
+/**
+ * Hook to get usage metrics for features
+ */
+export declare function useUsageMetrics(featureKey?: string): UseQueryResult<    {
+metrics: UsageMetric[];
+}, Error>;
+
+/**
+ * Thrown when the request fails validation (400)
+ */
+export declare class ValidationError extends BillingOSError {
+    constructor(message?: string, data?: unknown);
+}
+
+export declare function WarningBanner({ type, message, actionLabel, onAction, className, }: WarningBannerProps): JSX.Element;
+
+declare interface WarningBannerProps {
+    type: 'trial_ending' | 'payment_failed' | 'subscription_canceled' | 'past_due';
+    message: string;
+    actionLabel?: string;
+    onAction?: () => void;
+    className?: string;
+}
+
+export { }