@meetreeve/billing-kit 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,434 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { ReactNode } from 'react';
+
+/**
+ * Catalog types mirroring reeve-services `packages/commerce/types.py` →
+ * `Catalog.to_public_dict()`, served by `GET /api/v2/commerce/catalog/{host_app}`.
+ * Structurally identical to reeve-frontend's app-local mirror
+ * (`src/lib/api/commerce.ts`) — duplicated here rather than imported so this
+ * package has zero dependency on reeve-frontend's `src/` tree and can be
+ * dropped into any consumer app (e.g. AgentPik) unchanged.
+ *
+ * DEV-1786: the wire payload doesn't carry `currency` / `popular` /
+ * `purchasable` yet — that's a reeve-services gap (`packages/commerce/types.py`)
+ * out of scope for this FE-only ticket (rs `packages/commerce/types.py` is
+ * collision-fenced this batch to DEV-5037). All three are OPTIONAL here so:
+ *   - a catalog that already has them (once the BE ships it) needs no type
+ *     change to start using them, and
+ *   - callers can inject the same effect today via `PricingTable`'s
+ *     `presentation` prop (badge/highlighted) without waiting on the BE.
+ * See the PR body for the concrete BE follow-up.
+ */
+interface CatalogPlan {
+    id: string;
+    name: string;
+    price_cents: number;
+    /** "month" | "year" | ... — whatever the catalog emits. */
+    interval: string;
+    credits_grant_monthly: number | null;
+    credits_grant_lifetime: number | null;
+    features: string[];
+    /**
+     * key → -1 unlimited | 0 blocked | N capped. e.g. `{ seats, brands_max, voice }`.
+     * Same -1/0/N convention as reeve-services' `Entitlements` (packages/commerce/entitlements.py).
+     */
+    feature_limits: Record<string, number>;
+    support_tier: string | null;
+    /** Gap field (not yet on the wire) — ISO 4217 currency code, e.g. "usd". */
+    currency?: string;
+    /** Gap field (not yet on the wire) — highlight this as the recommended tier. */
+    popular?: boolean;
+    /** Gap field (not yet on the wire) — false disables the CTA (e.g. a retired tier still returned for existing subscribers). Defaults to true. */
+    purchasable?: boolean;
+}
+interface CatalogPack {
+    id: string;
+    name: string;
+    credits: number;
+    price_cents: number;
+    /** Gap field (not yet on the wire) — ISO 4217 currency code, e.g. "usd". */
+    currency?: string;
+}
+interface Catalog {
+    host_app: string;
+    plans: CatalogPlan[];
+    packs: CatalogPack[];
+}
+/**
+ * Normalized credit balance (DEV-1787). The two source payloads diverge —
+ * Studio's legacy `{total, base_credits, top_up_credits, byok_available,
+ * base_credits_expire_at}` (reeve-frontend `src/lib/api/credits.ts`) vs
+ * AgentPik's `{balance, base, top_up, expiring_soon}` — and AgentPik's own
+ * `normalizeCreditBalance` (`lib/api/studio.ts`) already emits this exact
+ * shape, so it's adopted as the package's contract. Every app maps its own
+ * wire shape onto this with a small app-side adapter (never in the
+ * package) before it reaches `CreditsMeter` / `LowBalanceBanner`.
+ */
+interface CreditBalance {
+    /** Whole running balance — base + top-up (+ any carryover). */
+    total: number;
+    /** Remaining plan-grant credits for the current period (or lifetime grant). */
+    base_credits: number;
+    /** Purchased top-up credits (roll over, don't reset with the billing period). */
+    top_up_credits: number;
+    /** Credits due to expire soon — units match `total` (credits, not a date). Optional: not every app tracks this. */
+    expiring_soon?: number;
+    /** ISO date the base-credit grant expires, if the app tracks per-grant expiry. */
+    base_credits_expire_at?: string | null;
+    /** True when the account has "bring your own key" — usage isn't metered against the balance. */
+    byok_available?: boolean;
+}
+/**
+ * The credits `view` payload — mirrors reeve-services'
+ * `GET /api/v1/credits/view/{owner_id}` (`packages/credits/service.py`,
+ * `api/routers/credits_host_app.py`). The BE already branches per host_app
+ * via the Credits registry's `display_mode` (`packages/credits/registry.py`:
+ * "balance" | "percentage"), so `CreditsMeter` renders whichever `mode` it's
+ * handed rather than re-deriving it from a bare registry flag.
+ */
+interface CreditsView {
+    mode: "balance" | "percentage" | "unavailable";
+    /** percentage mode only — 0-100. */
+    percentage_used?: number;
+    /** percentage mode only — ISO date the usage window resets. */
+    reset_at?: string | null;
+    /** balance mode only — the running total (a bare number; pass the full normalized `CreditBalance` as `CreditsMeter`'s `balance` prop for the base/top-up detail rows). */
+    balance?: number;
+    /** balance mode only. */
+    expiring_soon?: number;
+    owner_type?: string;
+    /** unavailable mode only — why (e.g. no ledger exists yet for this owner). */
+    reason?: string;
+}
+
+/** Whole-dollar amount from integer cents ($20 from 2000). */
+declare function dollarsFromCents(cents: number): number;
+/**
+ * Minimal, dependency-free price formatter. Good enough for the catalog's
+ * only currently-live currency (USD, `currency` is a DEV-1786 gap field —
+ * see types.ts). Swap for `Intl.NumberFormat` per-currency once the catalog
+ * actually carries non-USD plans.
+ */
+declare function formatPrice(cents: number, currency?: string): string;
+/** Thousands-separated credit count, e.g. 100000 -> "100,000". */
+declare function formatCredits(n: number): string;
+
+/**
+ * Client-side mirror of reeve-services' `Entitlements.min_tier_for`
+ * (`packages/commerce/entitlements.py`) — the lowest catalog-order plan
+ * whose `feature_limits[featureKey]` is present and non-zero. Same
+ * -1 (unlimited) / 0 (blocked) / N (capped) convention as the BE.
+ *
+ * "Catalog order IS tier order" — `commerce_bootstrap.py` registers plans
+ * low-to-high, and `to_public_dict()` preserves that order on the wire, so
+ * this does not re-sort by price. A featureKey absent from a plan's
+ * `feature_limits` entirely is treated as blocked (0), not unlocked — a
+ * catalog that hasn't been told about a feature must never produce a false
+ * unlock.
+ *
+ * Returns `null` when no plan in the catalog unlocks the feature at all
+ * (e.g. a misconfigured catalog, or a feature nothing has been wired to
+ * yet) — callers (see `UpgradePaywall`) must handle this without dead-ending
+ * the CTA.
+ */
+declare function resolveUnlockingPlan(plans: CatalogPlan[], featureKey: string): CatalogPlan | null;
+/** Whether `plan` already unlocks `featureKey` (non-zero limit, incl. -1 unlimited). */
+declare function isFeatureUnlocked(plan: CatalogPlan | null | undefined, featureKey: string): boolean;
+/** True when `limit` means "no cap" in the BE's -1/0/N convention. */
+declare function isUnlimited(limit: number | undefined): boolean;
+
+/**
+ * Per-plan-id presentation overlay. Marketing copy stays app-side — the
+ * catalog stays the source of truth for price, credits, and feature
+ * bullets. Mirrors AgentPik's `PLAN_STYLE` pattern (#204).
+ */
+interface PlanPresentation {
+    /** Small pill/badge label, e.g. "Most popular". Overrides `plan.popular`. */
+    badge?: string;
+    /** One-line marketing hook rendered under the price. */
+    tagline?: string;
+    /** Extra className merged onto the card — app-level accent/highlight styling. */
+    className?: string;
+    /** Force the highlighted treatment regardless of `plan.popular`. */
+    highlighted?: boolean;
+    /** CTA label override. Defaults to "Current plan" / "Get {name}". */
+    cta?: string;
+}
+interface PricingTableProps {
+    /** Injected, not fetched — the caller owns the `getCatalog()` call (RSC or client). */
+    catalog: Catalog;
+    /** "grid" = full tier comparison (Studio/reeve shape). "band" = single highlighted plan (AgentPik shape). Default "grid". */
+    variant?: "grid" | "band";
+    /** Which plan to feature in "band" mode. Falls back to `currentPlanId`, then the `popular` plan, then the first plan. */
+    bandPlanId?: string;
+    /** Render the credit-pack grid below the plans. Default: true iff `catalog.packs.length`. */
+    showPacks?: boolean;
+    /** Signed-in user's current plan id — drives the "Your plan" badge + CTA state. */
+    currentPlanId?: string | null;
+    /** Per-plan-id presentation overlay (badge/tagline/style). Marketing copy stays app-side. */
+    presentation?: Record<string, PlanPresentation>;
+    /** Checkout wiring stays app-local/injected — called when a plan's CTA is clicked. */
+    onSelectPlan?: (plan: CatalogPlan) => void | Promise<void>;
+    /** Called when a pack's Buy CTA is clicked. */
+    onBuyPack?: (pack: CatalogPack) => void | Promise<void>;
+    className?: string;
+}
+/**
+ * Catalog-driven pricing surface — tier grid, single-plan band, and/or
+ * credit-pack cards. Renders from an INJECTED `catalog` (never fetches — the
+ * caller owns `getCatalog()` / RSC data flow), so a price/bullet edit in the
+ * reeve-services catalog SSOT changes the rendered page with zero FE deploy.
+ */
+declare function PricingTable({ catalog, variant, bandPlanId, showPacks, currentPlanId, presentation, onSelectPlan, onBuyPack, className, }: PricingTableProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * DEV-2917's 402 `upgrade_options` payload shape (`["plan", "addon"]`) —
+ * pass it straight through when the caller already has it from a 402
+ * response, to control which CTA(s) render. Defaults to `["plan"]`.
+ */
+type UpgradeOption = "plan" | "addon";
+interface UpgradePaywallProps {
+    /** The gated capability — keyed the same as the catalog's `feature_limits` (e.g. "brands_max"). */
+    featureKey: string;
+    catalog: Catalog;
+    currentPlanId?: string | null;
+    /** "modal" (default) renders in a Radix Dialog; "inline" renders as a plain card. */
+    variant?: "modal" | "inline";
+    /** Modal-only. Ignored for `variant="inline"`. Defaults to `true` (always visible) so an inline embed and a controlled modal share the same component without extra plumbing. */
+    open?: boolean;
+    onClose?: () => void;
+    /**
+     * Fires with the resolved unlocking plan when the primary CTA is clicked.
+     * Checkout wiring (Stripe, etc.) stays app-local/injected. The CTA is
+     * never a dead end: if no tier unlocks the feature, this still fires with
+     * the catalog's top-tier plan so the caller has something concrete to act
+     * on (e.g. route to a general pricing/contact page).
+     */
+    onUpgrade?: (plan: CatalogPlan) => void | Promise<void>;
+    /** Which CTA(s) to render — DEV-2917's 402 `upgrade_options` shape. Defaults to `["plan"]`. */
+    upgradeOptions?: UpgradeOption[];
+    /** Required when `upgradeOptions` includes "addon". */
+    onAddon?: () => void | Promise<void>;
+    addonLabel?: string;
+    /** App-local escape hatch (e.g. Studio's "Delete an existing brand instead") — kept generic so copy/behavior stays app-side. */
+    secondaryAction?: {
+        label: string;
+        onClick: () => void;
+        disabled?: boolean;
+    };
+    title?: string;
+    description?: string;
+    className?: string;
+}
+/**
+ * Feature-gated upgrade paywall. Resolves the lowest-tier plan that unlocks
+ * `featureKey` from the injected `catalog` (client-side mirror of
+ * reeve-services' `Entitlements.min_tier_for`) and always renders a working
+ * upgrade CTA — no dead-end paywalls (cf. the `BrandQuotaPaywall` "Delete an
+ * existing brand" pattern this replaces, DEV-823).
+ */
+declare function UpgradePaywall(props: UpgradePaywallProps): react_jsx_runtime.JSX.Element;
+
+interface AutoCheckoutProps {
+    /** Validated against these before firing — never trusts a bare URL id. */
+    packs?: CatalogPack[];
+    plans?: CatalogPlan[];
+    onBuyPack?: (pack: CatalogPack) => void | Promise<void>;
+    onSelectPlan?: (plan: CatalogPlan) => void | Promise<void>;
+    /** Query param read for a pending pack purchase. Default "credits". */
+    packParam?: string;
+    /** Query param read for a pending plan subscription. Default "plan". */
+    planParam?: string;
+}
+/**
+ * Post-login/return auto-checkout resume. Drop anywhere on a pricing
+ * surface: reads `?<packParam>=<id>` / `?<planParam>=<id>` from the URL
+ * (validated against the injected catalog data, never a bare id) and fires
+ * the matching handler once, then strips the param so a refresh can't
+ * re-fire it. Seeded from AgentPik's `AutoCheckout` (#204) — ref-guarded so
+ * StrictMode's double-effect can't double-fire.
+ *
+ * Deliberately framework-agnostic: uses `window.history.replaceState`
+ * instead of `next/navigation`'s `useRouter()` for the param-strip. Two
+ * reasons, not just one:
+ *   1. Portability — this package has no other Next.js-only dependency, and
+ *      a raw History API call works identically in a Vite SPA consumer
+ *      (e.g. a future non-Next host) with zero extra plumbing.
+ *   2. A real bundling hazard: `next` is a peer dependency here, but
+ *      `next/navigation`'s router context is a *runtime singleton* keyed to
+ *      the exact `next` module instance the host app's tree was rendered
+ *      with. Pulling `useRouter` in from this package's own bundle risked
+ *      resolving a second `next` instance (pnpm content-addresses `next` by
+ *      its full peer-resolution hash, so "same semver range" doesn't
+ *      guarantee "same physical module" the way it does for `react`) —
+ *      observed concretely as `next`'s real router throwing "invariant
+ *      expected app router to be mounted" instead of the host app's test
+ *      mock intercepting it. `window.history` has no such identity concern.
+ * Reading via `window.location` (not `useSearchParams()`) is the same
+ * choice reeve-frontend's own newer `pricing-full.tsx` (DEV-2443) already
+ * made for this exact resume pattern, and sidesteps needing a Suspense
+ * boundary here at all.
+ */
+declare function AutoCheckout({ packs, plans, onBuyPack, onSelectPlan, packParam, planParam, }: AutoCheckoutProps): null;
+
+interface PlanCardProps {
+    /** The account's current plan, looked up from the catalog by id (app-side). Null renders a "no plan on file" empty state — never a blank card. */
+    plan: CatalogPlan | null;
+    /** ISO date string — rendered as "Renews {date}" when present. */
+    renewalDate?: string | null;
+    /** Subscription status (e.g. "active" | "trialing" | "past_due" | "canceled"). Omit or "free" hides the status pill. */
+    status?: string | null;
+    /** True for the free tier — swaps the CTA row to a single primary "Upgrade" action instead of manage/change. */
+    isFreePlan?: boolean;
+    /** Opens the Stripe customer portal / app-local subscription management. Omit to hide the "Manage billing" CTA. */
+    onManage?: () => void | Promise<void>;
+    manageLabel?: string;
+    /** Fires for the free-plan CTA ("Upgrade") or the paid-plan "Change plan" CTA. Omit to hide. */
+    onChangePlan?: () => void | Promise<void>;
+    changePlanLabel?: string;
+    className?: string;
+}
+/**
+ * Current-plan summary card — tier, price, renewal date, and the
+ * manage/change-plan CTAs. Distinct from `PricingTable`'s internal
+ * (unexported) plan card: that one is a selectable tier in a comparison
+ * grid; this one is a single-plan status summary for the account settings
+ * surface. Renders from an INJECTED `plan` (the caller resolves it from the
+ * catalog by id) — this component never fetches.
+ */
+declare function PlanCard({ plan, renewalDate, status, isFreePlan, onManage, manageLabel, onChangePlan, changePlanLabel, className, }: PlanCardProps): react_jsx_runtime.JSX.Element;
+
+interface CreditsMeterProps {
+    /**
+     * The credits `view` payload (`GET /api/v1/credits/view/{owner_id}`) —
+     * this component renders `view.mode` directly rather than re-deriving a
+     * display mode from a bare registry flag. Freya is registered
+     * "percentage"; Studio/AgentPik/reeve are registered "balance".
+     */
+    view: CreditsView;
+    /**
+     * Optional normalized balance for the balance-mode detail rows
+     * (base/top-up split, expiry, BYOK badge). `view.balance` alone only
+     * carries the running total — pass this when the caller already has the
+     * fuller balance object (e.g. from its own credits fetch).
+     */
+    balance?: CreditBalance;
+    className?: string;
+}
+/**
+ * Usage/credits meter — same component for both Credits registry display
+ * modes (DEV-1787): Freya-style "% of allowance used" and Studio/AgentPik-
+ * style "credits remaining". Renders from an INJECTED `view` payload; never
+ * fetches.
+ */
+declare function CreditsMeter({ view, balance, className }: CreditsMeterProps): react_jsx_runtime.JSX.Element;
+
+interface BuyMorePacksProps {
+    packs: CatalogPack[];
+    /**
+     * "fixed-pack" (AgentPik shape) renders a card grid, one CTA per pack.
+     * "presets" (Studio shape) renders a compact row of quick-buy chips.
+     * Both purchase the same catalog-driven `CatalogPack` — the config only
+     * changes the layout, so a consumer picks whichever matches its existing
+     * buy-flow density without the package needing two data shapes.
+     */
+    purchaseModel?: "fixed-pack" | "presets";
+    /** Checkout wiring stays app-local/injected — called when a pack's CTA is clicked. */
+    onPurchase: (pack: CatalogPack) => void | Promise<void>;
+    /**
+     * Query param read for a just-completed top-up checkout return, e.g.
+     * `?topup=success`. Default "topup". The param is always stripped from
+     * the URL on mount if present, whether or not `onTopupSuccess` is given.
+     */
+    successParam?: string;
+    /**
+     * Fires when `?<successParam>=success` is present on mount — seeded from
+     * AgentPik's post-checkout re-poll (#205): fires at 0s/2s/5s since the
+     * ledger webhook can lag the checkout redirect by a couple seconds.
+     */
+    onTopupSuccess?: () => void | Promise<void>;
+    className?: string;
+}
+/**
+ * Catalog-driven credit-pack purchase flow, plus the post-checkout
+ * `?topup=success` resume. Renders from an INJECTED `packs` list (never
+ * fetches — the caller owns `getCatalog()`).
+ */
+declare function BuyMorePacks({ packs, purchaseModel, onPurchase, successParam, onTopupSuccess, className, }: BuyMorePacksProps): react_jsx_runtime.JSX.Element | null;
+
+interface LowBalanceBannerProps {
+    /** Normalized balance — always injected. Unlike the reeve-frontend original this ported from, this component never fetches. */
+    balance: CreditBalance;
+    /** Daily burn rate (credits/day) for a "running out soon" warning alongside the fixed low-balance threshold. */
+    burnRate?: number;
+    /** Balance below which "low" fires. Default 5 — mirrors the legacy `LOW_BALANCE_THRESHOLD`. */
+    threshold?: number;
+    variant?: "default" | "compact";
+    /** Buy-credits CTA — app-local routing/checkout stays injected. Omit to hide the CTA. */
+    onAddCredits?: () => void;
+    addCreditsLabel?: string;
+    /** BYOK CTA, shown alongside the empty-balance state. Omit to hide it. */
+    onAddByok?: () => void;
+    addByokLabel?: string;
+    className?: string;
+}
+/**
+ * Low/zero-balance warning banner (DEV-1787, ported from reeve-frontend's
+ * `src/components/credits/low-balance-banner.tsx`). Props-only — the
+ * original self-fetched via `getBalance()`; here `balance` is always
+ * injected so the package never makes an HTTP call. BYOK accounts (usage
+ * isn't metered against the balance) never see the warning.
+ */
+declare function LowBalanceBanner({ balance, burnRate, threshold, variant, onAddCredits, addCreditsLabel, onAddByok, addByokLabel, className, }: LowBalanceBannerProps): react_jsx_runtime.JSX.Element | null;
+
+interface BillingSettingsPanelProps {
+    /** Current plan, looked up from the catalog by id (app-side). Null renders PlanCard's empty state. */
+    plan: CatalogPlan | null;
+    renewalDate?: string | null;
+    planStatus?: string | null;
+    isFreePlan?: boolean;
+    onManagePlan?: () => void | Promise<void>;
+    manageLabel?: string;
+    onChangePlan?: () => void | Promise<void>;
+    changePlanLabel?: string;
+    creditsView: CreditsView;
+    creditsBalance?: CreditBalance;
+    /** Default true — hidden entirely when `creditsBalance` is omitted (nothing to evaluate the threshold against). */
+    showLowBalanceBanner?: boolean;
+    lowBalanceThreshold?: number;
+    burnRate?: number;
+    onAddCredits?: () => void;
+    addCreditsLabel?: string;
+    onAddByok?: () => void;
+    packs?: CatalogPack[];
+    purchaseModel?: "fixed-pack" | "presets";
+    onBuyPack?: (pack: CatalogPack) => void | Promise<void>;
+    topupSuccessParam?: string;
+    onTopupSuccess?: () => void | Promise<void>;
+    /** When provided (and `showUpgradeSection` isn't false), renders the catalog-driven upgrade section below Buy more. */
+    catalog?: Catalog;
+    /** Default: renders whenever `catalog` is provided. Set false to suppress even with a catalog (e.g. a paid plan that only wants the PlanCard's own "Change plan" CTA). */
+    showUpgradeSection?: boolean;
+    upgradeVariant?: "grid" | "band";
+    upgradePresentation?: Record<string, PlanPresentation>;
+    onSelectPlan?: (plan: CatalogPlan) => void | Promise<void>;
+    /**
+     * Owner-scoped ledger/history UI is out of scope pending DEV-1188 — the
+     * package ships no built-in history list. Pass a caller-owned node (e.g.
+     * an app's existing ledger table) to render it here; omit to keep the
+     * slot fully inert (renders nothing, not an empty placeholder).
+     */
+    historySlot?: ReactNode;
+    className?: string;
+}
+/**
+ * Thin composition of the DEV-1787 billing primitives (`PlanCard` /
+ * `CreditsMeter` / `BuyMorePacks` / `LowBalanceBanner`) plus DEV-1786's
+ * `PricingTable` as the embedded upgrade slot. All data + handlers are
+ * injected — this component never fetches. Sections that have nothing to
+ * render (no packs, no catalog, no history node) render nothing rather
+ * than an empty shell.
+ */
+declare function BillingSettingsPanel({ plan, renewalDate, planStatus, isFreePlan, onManagePlan, manageLabel, onChangePlan, changePlanLabel, creditsView, creditsBalance, showLowBalanceBanner, lowBalanceThreshold, burnRate, onAddCredits, addCreditsLabel, onAddByok, packs, purchaseModel, onBuyPack, topupSuccessParam, onTopupSuccess, catalog, showUpgradeSection, upgradeVariant, upgradePresentation, onSelectPlan, historySlot, className, }: BillingSettingsPanelProps): react_jsx_runtime.JSX.Element;
+
+export { AutoCheckout, type AutoCheckoutProps, BillingSettingsPanel, type BillingSettingsPanelProps, BuyMorePacks, type BuyMorePacksProps, type Catalog, type CatalogPack, type CatalogPlan, type CreditBalance, CreditsMeter, type CreditsMeterProps, type CreditsView, LowBalanceBanner, type LowBalanceBannerProps, PlanCard, type PlanCardProps, type PlanPresentation, PricingTable, type PricingTableProps, type UpgradeOption, UpgradePaywall, type UpgradePaywallProps, dollarsFromCents, formatCredits, formatPrice, isFeatureUnlocked, isUnlimited, resolveUnlockingPlan };