@bpinternal/billing-ui 0.0.2 → 0.2.0

package/dist/index.d.ts

@@ -58,6 +58,8 @@ export declare type AddonsSummaryCardProps = {
     className?: string;
 };
 
+export declare const ArrowRightIcon: ({ size, ...props }: IconProps) => JSX.Element;
+
 export declare const Badge: ({ variant, children, className }: BadgeProps) => JSX.Element;
 
 export declare type BadgeProps = {
@@ -68,6 +70,24 @@ export declare type BadgeProps = {
 
 export declare const BankIcon: ({ size, ...props }: IconProps) => JSX.Element;
 
+export declare const BILLING_EVENTS: {
+    readonly PLAN_PICKER_VIEWED: "billing_plan_picker_viewed";
+    readonly PLAN_INTERVAL_TOGGLED: "billing_plan_interval_toggled";
+    readonly PLAN_UPGRADE_INITIATED: "billing_plan_upgrade_initiated";
+    readonly PLAN_DOWNGRADED: "billing_plan_downgraded";
+    readonly PLAN_DOWNGRADE_CANCELLED: "billing_plan_downgrade_cancelled";
+    readonly CHECKOUT_STEP_VIEWED: "billing_checkout_step_viewed";
+    readonly CHECKOUT_INTERVAL_CHANGED: "billing_checkout_interval_changed";
+    readonly PAYMENT_METHOD_SELECTED: "billing_payment_method_selected";
+    readonly PAYMENT_DETAILS_CONFIRMED: "billing_payment_details_confirmed";
+    readonly PLAN_UPGRADED: "billing_plan_upgraded";
+    readonly CHECKOUT_ERROR: "billing_checkout_error";
+    readonly PAYMENT_METHOD_UPDATED: "billing_payment_method_updated";
+    readonly BILLING_ADDRESS_UPDATED: "billing_address_updated";
+    readonly INVOICE_DOWNLOADED: "billing_invoice_downloaded";
+    readonly UPGRADE_CTA_CLICKED: "billing_upgrade_cta_clicked";
+};
+
 export declare type BillingAddress = {
     lineOne: string;
     lineTwo?: string;
@@ -77,32 +97,17 @@ export declare type BillingAddress = {
     country: string;
 };
 
-export declare type BillingAnalytics = {
-    trackPaymentDetailsConfirmed?: (props: {
-        plan_name: string;
-        interval: BillingInterval;
-    }) => void;
-    trackPlanUpgradeInitiated?: (props: {
-        plan_name: string;
-        interval: BillingInterval;
-        current_plan_name?: string;
-    }) => void;
-    trackPlanUpgraded?: (props: {
-        plan_name: string;
-        interval: BillingInterval;
-        amount_paid: number;
-        next_cycle_amount: number;
-        previous_plan_name?: string;
-        previous_interval?: BillingInterval;
-    }) => void;
-    trackPlanDowngraded?: (props: {
-        plan_name: string;
-        interval: BillingInterval;
-        previous_plan_name?: string;
-    }) => void;
-    trackPlanDowngradeCancelled?: (props: {
-        plan_name: string;
-    }) => void;
+/**
+ * Analytics sink the library captures billing events into. Structurally a subset
+ * of a `posthog-js` instance — pass `posthog` straight in (no adapter), or any
+ * object with a matching `capture`. The library never imports an analytics SDK,
+ * so it stays publishable and provider-agnostic. Omit it and every event no-ops.
+ *
+ * Event names + property shapes the library emits live in `BILLING_EVENTS`
+ * (./analytics) — that's the source of truth for what lands in your project.
+ */
+export declare type BillingAnalyticsClient = {
+    capture: (event: string, properties?: Record<string, unknown>) => void;
 };
 
 export declare type BillingChangeEvent = {
@@ -137,7 +142,7 @@ declare type BillingContextValue = {
     locale: string;
     isDark: boolean;
     toast: (toast: BillingToast) => void;
-    analytics: BillingAnalytics;
+    analytics: BillingAnalyticsClient;
     featureLabels?: Record<string, (quantity: number) => string>;
     isOutdatedBilling: boolean;
     manageBillingUrl?: string;
@@ -149,6 +154,8 @@ declare type BillingContextValue = {
     notifyBillingChange: (event: BillingChangeEvent) => void;
 };
 
+export declare type BillingEventName = (typeof BILLING_EVENTS)[keyof typeof BILLING_EVENTS];
+
 export declare type BillingInterval = 'month' | 'year';
 
 export declare const billingKeys: {
@@ -180,7 +187,13 @@ export declare type BillingProviderProps = {
     locale?: string;
     theme?: BillingTheme;
     onToast?: (toast: BillingToast) => void;
-    analytics?: BillingAnalytics;
+    /**
+     * Analytics sink the library captures billing-funnel events into. Pass a
+     * `posthog-js` instance directly (it satisfies the shape), or any object with
+     * a matching `capture`. Omit and every event no-ops. The event names + props
+     * the library emits are listed in `BILLING_EVENTS`.
+     */
+    analytics?: BillingAnalyticsClient;
     /** Override the human label shown for a plan feature key (e.g. bot_count) */
     featureLabels?: Record<string, (quantity: number) => string>;
     /**
@@ -469,6 +482,44 @@ export declare const NANO_DOLLARS_PER_DOLLAR = 1000000000;
  */
 export declare const OutdatedBillingGate: () => JSX.Element;
 
+/**
+ * Free-plan upgrade modal — the proactive nudge shown when a Free workspace is
+ * about to run out of its one-time conversation allowance. Frames the upgrade
+ * (monthly allowance + packs + more channels) and offers the two self-serve
+ * paid tiers (Plus / Team) with the same plan-card language as the pricing
+ * table. Mount it once near the app root.
+ *
+ * Two modes:
+ * - **controlled** — pass `open` / `onOpenChange` and drive it yourself.
+ * - **auto** (omit `open`) — it opens itself when the workspace is on Free and
+ *   ≥75% through its conversations, at most once per day per workspace
+ *   (dismissed via localStorage, same as the usage banner). Returns the next day.
+ */
+export declare const OutgrowFreeDialog: ({ open, onOpenChange, onSelectPlan, recommendedPlanId, interval, planFeatures, featureDescriptions, period, }: OutgrowFreeDialogProps) => JSX.Element | null;
+
+export declare type OutgrowFreeDialogProps = {
+    /**
+     * Controlled visibility. Omit to let the dialog manage itself in `auto` mode:
+     * it opens on its own when the workspace is on the Free plan and has used
+     * ≥75% of its conversation allowance — at most once per day per workspace.
+     */
+    open?: boolean;
+    /** Required in controlled mode; also called when the dialog closes in auto mode. */
+    onOpenChange?: (open: boolean) => void;
+    /** Called when the user picks a plan — open your CheckoutDialog with these values. */
+    onSelectPlan: (planId: string, interval: BillingInterval) => void;
+    /** Plan kind (or exact id) to mark Recommended. Default 'team'. */
+    recommendedPlanId?: string;
+    /** Billing interval the prices are shown at. Default 'year' (annual). */
+    interval?: BillingInterval;
+    /** Per-kind marketing feature strings; defaults to DEFAULT_PLAN_FEATURES. */
+    planFeatures?: Partial<Record<PlanKind, string[]>>;
+    /** Feature label → tooltip description; merged over DEFAULT_FEATURE_DESCRIPTIONS. */
+    featureDescriptions?: Record<string, string>;
+    /** Period (any datetime in the billing month) to evaluate usage; defaults to current month. */
+    period?: string;
+};
+
 export declare const PaintIcon: ({ size, ...props }: IconProps) => JSX.Element;
 
 export declare type PaymentMethod = NonNullable<Awaited<ReturnType<BillingClient['getPaymentMethod']>>['paymentMethod']>;
@@ -712,7 +763,11 @@ export declare type UsageBannerProps = {
      * checkout so it works with zero host wiring.
      */
     onUpgrade?: () => void;
-    /** Show a dismiss (×) button. The banner reappears on remount. Default true. */
+    /**
+     * Show a dismiss (×) button. Dismissing hides the banner (for that metric) for
+     * the rest of the day via localStorage; it returns the next day or if a
+     * different metric crosses the threshold. Default true.
+     */
     dismissible?: boolean;
     /** CTA label. Default "Upgrade plan". */
     ctaLabel?: string;
@@ -766,7 +821,7 @@ export declare function usageItems(quotas: WorkspaceUsages | undefined): UsageIt
  * hover/focus after `delay`. Renders the children plainly on legacy billing
  * or when there's no usage to show (the popover just never opens).
  */
-export declare const UsagePopover: ({ children, delay, placement, period, className }: UsagePopoverProps) => JSX.Element;
+export declare const UsagePopover: ({ children, delay, placement, period, onUpgrade, block, className, }: UsagePopoverProps) => JSX.Element;
 
 export declare type UsagePopoverProps = {
     /** The trigger — hovering/focusing it reveals the usage popover. */
@@ -777,6 +832,14 @@ export declare type UsagePopoverProps = {
     placement?: 'top' | 'bottom';
     /** Period (any datetime in the billing month); defaults to current month. */
     period?: string;
+    /**
+     * Upgrade handler. When set, the popover shows a "Need more room?" nudge with a
+     * CTA on plans that can move up (e.g. Free). Wire it to your plan picker /
+     * billing route — same target as the widget's `onManage`.
+     */
+    onUpgrade?: () => void;
+    /** Stretch the trigger to fill its container (e.g. a full-width sidebar widget). */
+    block?: boolean;
     className?: string;
 };