@monetizekit/react 0.2.0 → 0.4.0

package/dist/index.d.cts

@@ -162,13 +162,31 @@ interface CreditBalance {
     balance: number;
     currency?: string;
 }
+interface TeamMember {
+    name: string;
+    email: string;
+    role: string;
+    avatarUrl?: string;
+}
+interface Invoice {
+    id: string;
+    /** ISO date string. */
+    date: string;
+    /** Amount in major currency units (e.g. dollars). */
+    amount: number;
+    currency: string;
+    status: "paid" | "pending" | "overdue";
+}
 
 interface PricingTableProps {
     /** Plans to render; if omitted, fetched live from the publishable-key API. */
     plans?: Plan[];
     /** Plan name to highlight as "Most Popular". */
     highlightPlan?: string;
+    /** Active billing cycle (controlled). With `showBillingToggle`, also the initial value. */
     billingCycle?: "monthly" | "annually";
+    /** Render an interactive Monthly/Yearly toggle above the cards. */
+    showBillingToggle?: boolean;
     locale?: string;
     onSelectPlan?: (planId: string) => void;
     /** Where the Contact Sales CTA links (defaults to no-op). */
@@ -181,7 +199,47 @@ interface PricingTableProps {
     /** Override the sample-data disclaimer copy. */
     disclaimer?: ReactNode;
 }
-declare function PricingTable({ plans: plansProp, highlightPlan, locale, onSelectPlan, onContactSales, sampleWhenEmpty, disclaimer, }: PricingTableProps): react.JSX.Element;
+declare function PricingTable({ plans: plansProp, highlightPlan, billingCycle, showBillingToggle, locale, onSelectPlan, onContactSales, sampleWhenEmpty, disclaimer, }: PricingTableProps): react.JSX.Element;
+
+/** A labelled group of feature keys to compare across plans. */
+interface ComparisonFeatureGroup {
+    title: string;
+    features: {
+        key: string;
+        label: string;
+    }[];
+}
+interface PricingComparisonProps {
+    /** Plans to compare; if omitted, fetched live from the publishable-key API. */
+    plans?: Plan[];
+    /**
+     * Feature groups (rows) to show. When omitted, a single "Features" group is
+     * derived from the union of the plans' entitlements.
+     */
+    groups?: ComparisonFeatureGroup[];
+    highlightPlan?: string;
+    billingCycle?: "monthly" | "annually";
+    locale?: string;
+    sampleWhenEmpty?: boolean;
+    disclaimer?: ReactNode;
+}
+/**
+ * A feature-comparison table across plans (à la a "Compare plans" section).
+ * Reads live plans via the publishable key when `plans` is omitted, and falls
+ * back to illustrative sample plans (behind a disclaimer) when empty.
+ */
+declare function PricingComparison({ plans: plansProp, groups, highlightPlan, billingCycle, locale, sampleWhenEmpty, disclaimer, }: PricingComparisonProps): react.JSX.Element;
+
+interface BillingCycleToggleProps {
+    value: "monthly" | "annually";
+    onChange: (value: "monthly" | "annually") => void;
+    /** When > 0, shows a "Save N%" hint on the Yearly option. */
+    savingsPercent?: number;
+    monthlyLabel?: string;
+    annuallyLabel?: string;
+}
+/** Monthly/Yearly billing switch used above pricing cards. */
+declare function BillingCycleToggle({ value, onChange, savingsPercent, monthlyLabel, annuallyLabel, }: BillingCycleToggleProps): react.JSX.Element;
 
 interface PaywallProps {
     /** Feature key gating the content. */
@@ -192,9 +250,11 @@ interface PaywallProps {
     description?: string;
     ctaLabel?: string;
     onUpgrade?: () => void;
+    /** Always render the locked upgrade prompt (for previews, no live customer). */
+    sample?: boolean;
 }
 /** Gate content behind an entitlement, showing an upgrade prompt when locked. */
-declare function Paywall({ feature, children, title, description, ctaLabel, onUpgrade, }: PaywallProps): react.JSX.Element;
+declare function Paywall({ feature, children, title, description, ctaLabel, onUpgrade, sample, }: PaywallProps): react.JSX.Element;
 
 interface UsageBannerProps {
     /** Meter to display usage for. */
@@ -207,6 +267,28 @@ interface UsageBannerProps {
 /** Show current usage vs allotment for a capacity meter, with overage hint. */
 declare function UsageBanner({ meterId, label, locale, warnAt, }: UsageBannerProps): react.JSX.Element;
 
+type AlertBannerVariant = "info" | "warning" | "danger" | "neutral";
+interface BannerAction {
+    label: string;
+    onClick?: () => void;
+    variant?: "primary" | "ghost";
+}
+interface AlertBannerProps {
+    variant?: AlertBannerVariant;
+    title: string;
+    description?: ReactNode;
+    /** Optional progress fraction (0–1) rendered as a colored bar. */
+    progress?: number;
+    actions?: BannerAction[];
+    /** Optional leading icon/emoji. */
+    icon?: ReactNode;
+}
+/**
+ * A flexible in-app notification banner (usage warnings, budget reached, low
+ * credits, trial ending, …). Presentational + fully themeable via tokens.
+ */
+declare function AlertBanner({ variant, title, description, progress, actions, icon, }: AlertBannerProps): react.JSX.Element;
+
 interface CustomerPortalProps {
     /** Current plan name to display. */
     planName?: string;
@@ -214,9 +296,19 @@ interface CustomerPortalProps {
     meterIds?: string[];
     /** Whether to show the credit balance card. */
     showCredits?: boolean;
+    /** Show a team/seats section. Defaults to on in `sample` mode. */
+    showTeam?: boolean;
+    teamMembers?: TeamMember[];
+    seats?: {
+        used: number;
+        max: number;
+    };
+    /** Show a billing-history (invoices) section. Defaults to on in `sample` mode. */
+    showInvoices?: boolean;
+    invoices?: Invoice[];
     /**
-     * Render illustrative sample plan/usage/credit data behind a clear disclaimer.
-     * Use for previews or a fresh workspace with no plans/products defined yet.
+     * Render illustrative sample plan/usage/credit/team/invoice data behind a clear
+     * disclaimer. Use for previews or a fresh workspace with no plans/products yet.
      */
     sample?: boolean;
     /** Override the sample-data disclaimer copy. */
@@ -227,8 +319,8 @@ interface CustomerPortalProps {
     currency?: string;
     onManageBilling?: () => void;
 }
-/** A self-service portal: current plan, usage meters, and credit balance. */
-declare function CustomerPortal({ planName, meterIds, showCredits, sample, disclaimer, showBranding, locale, currency, onManageBilling, }: CustomerPortalProps): react.JSX.Element;
+/** A self-service portal: plan, usage, credits, team, and invoices. */
+declare function CustomerPortal({ planName, meterIds, showCredits, showTeam, teamMembers, seats, showInvoices, invoices, sample, disclaimer, showBranding, locale, currency, onManageBilling, }: CustomerPortalProps): react.JSX.Element;
 
 interface EntitlementGateProps {
     /** Feature key to check for the provider's customer. */
@@ -263,6 +355,12 @@ declare function SampleNotice({ children }: SampleNoticeProps): react.JSX.Elemen
 declare const SAMPLE_PLANS: Plan[];
 declare const SAMPLE_USAGE: Record<string, UsageResult>;
 declare const SAMPLE_CREDITS: CreditBalance;
+declare const SAMPLE_TEAM: {
+    members: TeamMember[];
+    seats: number;
+    maxSeats: number;
+};
+declare const SAMPLE_INVOICES: Invoice[];
 declare const SAMPLE_PORTAL: {
     readonly planName: "Growth";
     readonly meterIds: readonly ["api_calls", "seats"];
@@ -286,8 +384,8 @@ interface PriceDisplay {
  * when the plan is tagged `contact_sales` or has no public price; renders a
  * "from $base + usage" headline when metered usage terms are present.
  */
-declare function describePlanPrice(plan: Plan, locale?: string): PriceDisplay;
+declare function describePlanPrice(plan: Plan, locale?: string, billingCycle?: "monthly" | "annually"): PriceDisplay;
 /** Human-readable description of a usage term's metered tiers. */
 declare function describeUsageTerm(term: PricingTerm, locale?: string): string;
 
-export { type Appearance, type CreditBalance, CustomerPortal, type CustomerPortalProps, EntitlementGate, type EntitlementGateProps, type EntitlementResult, MonetizeKitClient, type MonetizeKitClientConfig, type MonetizeKitContextValue, MonetizeKitProvider, type MonetizeKitProviderProps, Paywall, type PaywallProps, type Plan, type PlanEntitlement, type PriceDisplay, PricingTable, type PricingTableProps, type PricingTerm, type PricingTier, SAMPLE_CREDITS, SAMPLE_NOTICE_TEXT, SAMPLE_PLANS, SAMPLE_PORTAL, SAMPLE_USAGE, SampleNotice, type SampleNoticeProps, THEME_PRESETS, THEME_PRESET_NAMES, type ThemePresetName, type ThemeTokens, UsageBanner, type UsageBannerProps, type UsageResult, describePlanPrice, describeUsageTerm, formatMoney, formatUnits, resolveTokens, tokensToStyle, useCredits, useEntitlement, useMonetizeKit, useUsage };
+export { AlertBanner, type AlertBannerProps, type AlertBannerVariant, type Appearance, type BannerAction, BillingCycleToggle, type BillingCycleToggleProps, type ComparisonFeatureGroup, type CreditBalance, CustomerPortal, type CustomerPortalProps, EntitlementGate, type EntitlementGateProps, type EntitlementResult, type Invoice, MonetizeKitClient, type MonetizeKitClientConfig, type MonetizeKitContextValue, MonetizeKitProvider, type MonetizeKitProviderProps, Paywall, type PaywallProps, type Plan, type PlanEntitlement, type PriceDisplay, PricingComparison, type PricingComparisonProps, PricingTable, type PricingTableProps, type PricingTerm, type PricingTier, SAMPLE_CREDITS, SAMPLE_INVOICES, SAMPLE_NOTICE_TEXT, SAMPLE_PLANS, SAMPLE_PORTAL, SAMPLE_TEAM, SAMPLE_USAGE, SampleNotice, type SampleNoticeProps, THEME_PRESETS, THEME_PRESET_NAMES, type TeamMember, type ThemePresetName, type ThemeTokens, UsageBanner, type UsageBannerProps, type UsageResult, describePlanPrice, describeUsageTerm, formatMoney, formatUnits, resolveTokens, tokensToStyle, useCredits, useEntitlement, useMonetizeKit, useUsage };

package/dist/index.d.ts

@@ -162,13 +162,31 @@ interface CreditBalance {
     balance: number;
     currency?: string;
 }
+interface TeamMember {
+    name: string;
+    email: string;
+    role: string;
+    avatarUrl?: string;
+}
+interface Invoice {
+    id: string;
+    /** ISO date string. */
+    date: string;
+    /** Amount in major currency units (e.g. dollars). */
+    amount: number;
+    currency: string;
+    status: "paid" | "pending" | "overdue";
+}
 
 interface PricingTableProps {
     /** Plans to render; if omitted, fetched live from the publishable-key API. */
     plans?: Plan[];
     /** Plan name to highlight as "Most Popular". */
     highlightPlan?: string;
+    /** Active billing cycle (controlled). With `showBillingToggle`, also the initial value. */
     billingCycle?: "monthly" | "annually";
+    /** Render an interactive Monthly/Yearly toggle above the cards. */
+    showBillingToggle?: boolean;
     locale?: string;
     onSelectPlan?: (planId: string) => void;
     /** Where the Contact Sales CTA links (defaults to no-op). */
@@ -181,7 +199,47 @@ interface PricingTableProps {
     /** Override the sample-data disclaimer copy. */
     disclaimer?: ReactNode;
 }
-declare function PricingTable({ plans: plansProp, highlightPlan, locale, onSelectPlan, onContactSales, sampleWhenEmpty, disclaimer, }: PricingTableProps): react.JSX.Element;
+declare function PricingTable({ plans: plansProp, highlightPlan, billingCycle, showBillingToggle, locale, onSelectPlan, onContactSales, sampleWhenEmpty, disclaimer, }: PricingTableProps): react.JSX.Element;
+
+/** A labelled group of feature keys to compare across plans. */
+interface ComparisonFeatureGroup {
+    title: string;
+    features: {
+        key: string;
+        label: string;
+    }[];
+}
+interface PricingComparisonProps {
+    /** Plans to compare; if omitted, fetched live from the publishable-key API. */
+    plans?: Plan[];
+    /**
+     * Feature groups (rows) to show. When omitted, a single "Features" group is
+     * derived from the union of the plans' entitlements.
+     */
+    groups?: ComparisonFeatureGroup[];
+    highlightPlan?: string;
+    billingCycle?: "monthly" | "annually";
+    locale?: string;
+    sampleWhenEmpty?: boolean;
+    disclaimer?: ReactNode;
+}
+/**
+ * A feature-comparison table across plans (à la a "Compare plans" section).
+ * Reads live plans via the publishable key when `plans` is omitted, and falls
+ * back to illustrative sample plans (behind a disclaimer) when empty.
+ */
+declare function PricingComparison({ plans: plansProp, groups, highlightPlan, billingCycle, locale, sampleWhenEmpty, disclaimer, }: PricingComparisonProps): react.JSX.Element;
+
+interface BillingCycleToggleProps {
+    value: "monthly" | "annually";
+    onChange: (value: "monthly" | "annually") => void;
+    /** When > 0, shows a "Save N%" hint on the Yearly option. */
+    savingsPercent?: number;
+    monthlyLabel?: string;
+    annuallyLabel?: string;
+}
+/** Monthly/Yearly billing switch used above pricing cards. */
+declare function BillingCycleToggle({ value, onChange, savingsPercent, monthlyLabel, annuallyLabel, }: BillingCycleToggleProps): react.JSX.Element;
 
 interface PaywallProps {
     /** Feature key gating the content. */
@@ -192,9 +250,11 @@ interface PaywallProps {
     description?: string;
     ctaLabel?: string;
     onUpgrade?: () => void;
+    /** Always render the locked upgrade prompt (for previews, no live customer). */
+    sample?: boolean;
 }
 /** Gate content behind an entitlement, showing an upgrade prompt when locked. */
-declare function Paywall({ feature, children, title, description, ctaLabel, onUpgrade, }: PaywallProps): react.JSX.Element;
+declare function Paywall({ feature, children, title, description, ctaLabel, onUpgrade, sample, }: PaywallProps): react.JSX.Element;
 
 interface UsageBannerProps {
     /** Meter to display usage for. */
@@ -207,6 +267,28 @@ interface UsageBannerProps {
 /** Show current usage vs allotment for a capacity meter, with overage hint. */
 declare function UsageBanner({ meterId, label, locale, warnAt, }: UsageBannerProps): react.JSX.Element;
 
+type AlertBannerVariant = "info" | "warning" | "danger" | "neutral";
+interface BannerAction {
+    label: string;
+    onClick?: () => void;
+    variant?: "primary" | "ghost";
+}
+interface AlertBannerProps {
+    variant?: AlertBannerVariant;
+    title: string;
+    description?: ReactNode;
+    /** Optional progress fraction (0–1) rendered as a colored bar. */
+    progress?: number;
+    actions?: BannerAction[];
+    /** Optional leading icon/emoji. */
+    icon?: ReactNode;
+}
+/**
+ * A flexible in-app notification banner (usage warnings, budget reached, low
+ * credits, trial ending, …). Presentational + fully themeable via tokens.
+ */
+declare function AlertBanner({ variant, title, description, progress, actions, icon, }: AlertBannerProps): react.JSX.Element;
+
 interface CustomerPortalProps {
     /** Current plan name to display. */
     planName?: string;
@@ -214,9 +296,19 @@ interface CustomerPortalProps {
     meterIds?: string[];
     /** Whether to show the credit balance card. */
     showCredits?: boolean;
+    /** Show a team/seats section. Defaults to on in `sample` mode. */
+    showTeam?: boolean;
+    teamMembers?: TeamMember[];
+    seats?: {
+        used: number;
+        max: number;
+    };
+    /** Show a billing-history (invoices) section. Defaults to on in `sample` mode. */
+    showInvoices?: boolean;
+    invoices?: Invoice[];
     /**
-     * Render illustrative sample plan/usage/credit data behind a clear disclaimer.
-     * Use for previews or a fresh workspace with no plans/products defined yet.
+     * Render illustrative sample plan/usage/credit/team/invoice data behind a clear
+     * disclaimer. Use for previews or a fresh workspace with no plans/products yet.
      */
     sample?: boolean;
     /** Override the sample-data disclaimer copy. */
@@ -227,8 +319,8 @@ interface CustomerPortalProps {
     currency?: string;
     onManageBilling?: () => void;
 }
-/** A self-service portal: current plan, usage meters, and credit balance. */
-declare function CustomerPortal({ planName, meterIds, showCredits, sample, disclaimer, showBranding, locale, currency, onManageBilling, }: CustomerPortalProps): react.JSX.Element;
+/** A self-service portal: plan, usage, credits, team, and invoices. */
+declare function CustomerPortal({ planName, meterIds, showCredits, showTeam, teamMembers, seats, showInvoices, invoices, sample, disclaimer, showBranding, locale, currency, onManageBilling, }: CustomerPortalProps): react.JSX.Element;
 
 interface EntitlementGateProps {
     /** Feature key to check for the provider's customer. */
@@ -263,6 +355,12 @@ declare function SampleNotice({ children }: SampleNoticeProps): react.JSX.Elemen
 declare const SAMPLE_PLANS: Plan[];
 declare const SAMPLE_USAGE: Record<string, UsageResult>;
 declare const SAMPLE_CREDITS: CreditBalance;
+declare const SAMPLE_TEAM: {
+    members: TeamMember[];
+    seats: number;
+    maxSeats: number;
+};
+declare const SAMPLE_INVOICES: Invoice[];
 declare const SAMPLE_PORTAL: {
     readonly planName: "Growth";
     readonly meterIds: readonly ["api_calls", "seats"];
@@ -286,8 +384,8 @@ interface PriceDisplay {
  * when the plan is tagged `contact_sales` or has no public price; renders a
  * "from $base + usage" headline when metered usage terms are present.
  */
-declare function describePlanPrice(plan: Plan, locale?: string): PriceDisplay;
+declare function describePlanPrice(plan: Plan, locale?: string, billingCycle?: "monthly" | "annually"): PriceDisplay;
 /** Human-readable description of a usage term's metered tiers. */
 declare function describeUsageTerm(term: PricingTerm, locale?: string): string;
 
-export { type Appearance, type CreditBalance, CustomerPortal, type CustomerPortalProps, EntitlementGate, type EntitlementGateProps, type EntitlementResult, MonetizeKitClient, type MonetizeKitClientConfig, type MonetizeKitContextValue, MonetizeKitProvider, type MonetizeKitProviderProps, Paywall, type PaywallProps, type Plan, type PlanEntitlement, type PriceDisplay, PricingTable, type PricingTableProps, type PricingTerm, type PricingTier, SAMPLE_CREDITS, SAMPLE_NOTICE_TEXT, SAMPLE_PLANS, SAMPLE_PORTAL, SAMPLE_USAGE, SampleNotice, type SampleNoticeProps, THEME_PRESETS, THEME_PRESET_NAMES, type ThemePresetName, type ThemeTokens, UsageBanner, type UsageBannerProps, type UsageResult, describePlanPrice, describeUsageTerm, formatMoney, formatUnits, resolveTokens, tokensToStyle, useCredits, useEntitlement, useMonetizeKit, useUsage };
+export { AlertBanner, type AlertBannerProps, type AlertBannerVariant, type Appearance, type BannerAction, BillingCycleToggle, type BillingCycleToggleProps, type ComparisonFeatureGroup, type CreditBalance, CustomerPortal, type CustomerPortalProps, EntitlementGate, type EntitlementGateProps, type EntitlementResult, type Invoice, MonetizeKitClient, type MonetizeKitClientConfig, type MonetizeKitContextValue, MonetizeKitProvider, type MonetizeKitProviderProps, Paywall, type PaywallProps, type Plan, type PlanEntitlement, type PriceDisplay, PricingComparison, type PricingComparisonProps, PricingTable, type PricingTableProps, type PricingTerm, type PricingTier, SAMPLE_CREDITS, SAMPLE_INVOICES, SAMPLE_NOTICE_TEXT, SAMPLE_PLANS, SAMPLE_PORTAL, SAMPLE_TEAM, SAMPLE_USAGE, SampleNotice, type SampleNoticeProps, THEME_PRESETS, THEME_PRESET_NAMES, type TeamMember, type ThemePresetName, type ThemeTokens, UsageBanner, type UsageBannerProps, type UsageResult, describePlanPrice, describeUsageTerm, formatMoney, formatUnits, resolveTokens, tokensToStyle, useCredits, useEntitlement, useMonetizeKit, useUsage };