@molecule/app-billing-react 1.0.0

package/LICENSE

@@ -0,0 +1,115 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work.
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship.
+
+      "Contribution" shall mean any work of authorship, including the
+      original version of the Work and any modifications or additions
+      to that Work, that is intentionally submitted to the Licensor for
+      inclusion in the Work by the copyright owner or by an individual or
+      Legal Entity authorized to submit on behalf of the copyright owner.
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by the Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      patent license to make, have made, use, offer to sell, sell, import,
+      and otherwise transfer the Work.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file.
+
+   5. Submission of Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND.
+
+   8. Limitation of Liability. In no event and under no legal theory shall
+      any Contributor be liable to You for damages.
+
+   9. Accepting Warranty or Additional Liability.
+
+   Copyright 2026 Molecule Dev, Inc.
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/dist/BillingStatusBadge.d.ts

@@ -0,0 +1,24 @@
+/** Props for `<BillingStatusBadge />`. */
+export interface BillingStatusBadgeProps {
+    /**
+     * Optional callback invoked after a successful cancel. Most apps will
+     * navigate the user back to settings or refresh the page from here.
+     */
+    onCanceled?: () => void;
+    /** Optional className applied to the outer wrapper. */
+    className?: string;
+    /**
+     * Whether to render the cancel-subscription button when the user is
+     * on a paid tier. Defaults to `true`.
+     */
+    showCancel?: boolean;
+}
+/**
+ * Compact billing-status display for the user's account/settings page.
+ * Shows the current tier name and offers a cancel button on paid tiers.
+ *
+ * @param props - Component props.
+ * @returns The rendered status badge.
+ */
+export declare function BillingStatusBadge(props: BillingStatusBadgeProps): React.ReactElement | null;
+//# sourceMappingURL=BillingStatusBadge.d.ts.map

package/dist/BillingStatusBadge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"BillingStatusBadge.d.ts","sourceRoot":"","sources":["../src/BillingStatusBadge.tsx"],"names":[],"mappings":"AAKA,0CAA0C;AAC1C,MAAM,WAAW,uBAAuB;IACtC;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,IAAI,CAAA;IAEvB,uDAAuD;IACvD,SAAS,CAAC,EAAE,MAAM,CAAA;IAElB;;;OAGG;IACH,UAAU,CAAC,EAAE,OAAO,CAAA;CACrB;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,uBAAuB,GAAG,KAAK,CAAC,YAAY,GAAG,IAAI,CAuD5F"}

package/dist/BillingStatusBadge.js

@@ -0,0 +1,33 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useTranslation } from '@molecule/app-react';
+import { getClassMap } from '@molecule/app-ui';
+import { useBillingStatus, useCancelSubscription } from './hooks.js';
+/**
+ * Compact billing-status display for the user's account/settings page.
+ * Shows the current tier name and offers a cancel button on paid tiers.
+ *
+ * @param props - Component props.
+ * @returns The rendered status badge.
+ */
+export function BillingStatusBadge(props) {
+    const { onCanceled, className, showCancel = true } = props;
+    const cm = getClassMap();
+    const { t } = useTranslation();
+    const { data: status, loading, error } = useBillingStatus();
+    const { cancel, loading: canceling, error: cancelError } = useCancelSubscription();
+    if (loading) {
+        return (_jsx("span", { className: className, "data-mol-id": "billing-status-loading", children: t('billing.status.loading', undefined, { defaultValue: 'Loading…' }) }));
+    }
+    if (error || !status) {
+        return null;
+    }
+    const isFree = status.isFree;
+    const handleCancel = async () => {
+        const result = await cancel();
+        if (result?.canceled)
+            onCanceled?.();
+    };
+    return (_jsxs("div", { className: className, "data-mol-id": "billing-status", children: [_jsx("span", { className: cm.cardDescription, children: t('billing.status.currentPlan', { tierName: status.name }, { defaultValue: 'Current plan: {{tierName}}' }) }), showCancel && !isFree && (_jsx("button", { type: "button", className: cm.button({ variant: 'outline', size: 'sm' }), disabled: canceling, onClick: handleCancel, "data-mol-id": "billing-cancel-button", children: t('billing.status.cancelCta', undefined, { defaultValue: 'Cancel subscription' }) })), cancelError && (_jsx("p", { className: cm.formError, role: "alert", children: t('billing.status.cancelError', undefined, {
+                    defaultValue: 'Could not cancel. Please try again.',
+                }) }))] }));
+}

package/dist/PricingPage.d.ts

@@ -0,0 +1,114 @@
+import type { ReactNode } from 'react';
+import type { PricingTierPrice } from './types.js';
+/**
+ * Container for a tier's feature list. Apps use this in their
+ * `renderLimits` prop with `<LimitsItem>` children to get the polished
+ * stacked-checklist layout (check icon prefix, muted/primary colors,
+ * spacing) that matches the rest of `<PricingPage />`.
+ *
+ * @example
+ * ```tsx
+ * <PricingPage
+ *   renderLimits={(limits) => (
+ *     <LimitsList>
+ *       <LimitsItem>{t('pricing.blocks', { count: limits.maxBlocks })}</LimitsItem>
+ *       <LimitsItem included={limits.canExport}>{t('pricing.dataExport')}</LimitsItem>
+ *     </LimitsList>
+ *   )}
+ * />
+ * ```
+ */
+export declare function LimitsList({ children }: {
+    children: ReactNode;
+}): React.ReactElement;
+/** Props for `<LimitsItem>`. */
+export interface LimitsItemProps {
+    /** Row content (typically a translated label + number). */
+    children: ReactNode;
+    /**
+     * Whether this feature is included in the tier. When `false`, the row
+     * renders with a muted line-through and a dash glyph instead of the
+     * check icon. Defaults to `true`.
+     */
+    included?: boolean;
+}
+/**
+ * Single row in a tier's feature list — a check (or em-dash) icon
+ * followed by the row label. Use inside `<LimitsList>`.
+ */
+export declare function LimitsItem({ children, included }: LimitsItemProps): React.ReactElement;
+/** Props for `<PricingPage />`. */
+export interface PricingPageProps<TLimits = unknown> {
+    /**
+     * Optional billing-period selector. Defaults to `'month'`. Pass `'year'`
+     * to render the yearly column. The component falls back to whatever the
+     * tier provides when the requested period is missing.
+     */
+    period?: PricingTierPrice['period'];
+    /**
+     * Optional render function for the tier-specific limits column. Defaults
+     * to a stacked checklist rendering numeric / boolean values with a green
+     * check glyph. Apps with rich limit shapes can supply a custom renderer.
+     */
+    renderLimits?: (limits: TLimits) => React.ReactNode;
+    /**
+     * Optional override for the page-level heading translation key.
+     * Defaults to `'billing.pricing.heading'`.
+     */
+    headingKey?: string;
+    /** Optional English fallback for the heading. Defaults to `'Choose your plan'`. */
+    headingDefault?: string;
+    /**
+     * Optional sub-heading shown under the page heading. Pass `null` to
+     * suppress. Defaults to a translated "Pick the plan that fits…" line.
+     */
+    subheadingKey?: string | null;
+    /** English fallback for the sub-heading. */
+    subheadingDefault?: string;
+    /**
+     * Optional className applied to the outer wrapper, useful when embedding
+     * the page in an existing layout.
+     */
+    className?: string;
+    /**
+     * Path the browser is sent to when an anonymous visitor clicks a paid
+     * tier's upgrade CTA. Defaults to `/login`. Set to `null` to disable
+     * the redirect (e.g. when the app handles the auth gate at a higher
+     * level via routing guards).
+     */
+    unauthenticatedRedirect?: string | null;
+    /**
+     * Optional tier key to highlight as "most popular" — receives the
+     * elevated card variant, a popular-badge in the header, and a
+     * primary-tone CTA. When omitted (default), the highest-priced tier
+     * with a real stripePriceId for the selected period is auto-selected.
+     * Pass `null` to disable highlighting entirely.
+     */
+    popularTierKey?: string | null;
+    /**
+     * Optional font-family stack applied inline to the page heading,
+     * tier names, and hero price. Defaults to a system-serif cascade
+     * (Georgia, Iowan Old Style, …) matching the flagship-app
+     * convention. Pass `null` to disable inline font and inherit from
+     * the theme.
+     */
+    headlineFontFamily?: string | null;
+}
+/**
+ * Renders the public pricing page. Fetches `/api/billing/tiers` on mount
+ * and lays out one card per tier with the price for the selected period
+ * and a CTA that starts a Stripe Checkout session via
+ * `/api/billing/checkout`. Tiers without a Stripe priceId (e.g. the free
+ * tier or local-dev) render a disabled CTA so users still see the row.
+ *
+ * The highest-priced paid tier is highlighted as "most popular" by
+ * default — the card uses the elevated variant, the header carries a
+ * star badge, and its CTA renders in the primary color. Apps that want
+ * a different tier in the spotlight can pass `popularTierKey` (or
+ * `null` to suppress).
+ *
+ * @param props - Component props (see `PricingPageProps`).
+ * @returns The rendered pricing page.
+ */
+export declare function PricingPage<TLimits = unknown>(props: PricingPageProps<TLimits>): React.ReactElement;
+//# sourceMappingURL=PricingPage.d.ts.map

package/dist/PricingPage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"PricingPage.d.ts","sourceRoot":"","sources":["../src/PricingPage.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAA;AAOtC,OAAO,KAAK,EAAoB,gBAAgB,EAAE,MAAM,YAAY,CAAA;AAEpE;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,UAAU,CAAC,EAAE,QAAQ,EAAE,EAAE;IAAE,QAAQ,EAAE,SAAS,CAAA;CAAE,GAAG,KAAK,CAAC,YAAY,CAOpF;AAED,gCAAgC;AAChC,MAAM,WAAW,eAAe;IAC9B,2DAA2D;IAC3D,QAAQ,EAAE,SAAS,CAAA;IACnB;;;;OAIG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAA;CACnB;AAED;;;GAGG;AACH,wBAAgB,UAAU,CAAC,EAAE,QAAQ,EAAE,QAAe,EAAE,EAAE,eAAe,GAAG,KAAK,CAAC,YAAY,CAmB7F;AAwBD,mCAAmC;AACnC,MAAM,WAAW,gBAAgB,CAAC,OAAO,GAAG,OAAO;IACjD;;;;OAIG;IACH,MAAM,CAAC,EAAE,gBAAgB,CAAC,QAAQ,CAAC,CAAA;IAEnC;;;;OAIG;IACH,YAAY,CAAC,EAAE,CAAC,MAAM,EAAE,OAAO,KAAK,KAAK,CAAC,SAAS,CAAA;IAEnD;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAA;IAEnB,mFAAmF;IACnF,cAAc,CAAC,EAAE,MAAM,CAAA;IAEvB;;;OAGG;IACH,aAAa,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IAC7B,4CAA4C;IAC5C,iBAAiB,CAAC,EAAE,MAAM,CAAA;IAE1B;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAA;IAElB;;;;;OAKG;IACH,uBAAuB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IAEvC;;;;;;OAMG;IACH,cAAc,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IAE9B;;;;;;OAMG;IACH,kBAAkB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;CACnC;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,WAAW,CAAC,OAAO,GAAG,OAAO,EAC3C,KAAK,EAAE,gBAAgB,CAAC,OAAO,CAAC,GAC/B,KAAK,CAAC,YAAY,CAoJpB"}

package/dist/PricingPage.js

@@ -0,0 +1,305 @@
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { useAuth, useTranslation } from '@molecule/app-react';
+import { getClassMap } from '@molecule/app-ui';
+import { Icon } from '@molecule/app-ui-react';
+import { usePricingTiers, useStartCheckout } from './hooks.js';
+/**
+ * Container for a tier's feature list. Apps use this in their
+ * `renderLimits` prop with `<LimitsItem>` children to get the polished
+ * stacked-checklist layout (check icon prefix, muted/primary colors,
+ * spacing) that matches the rest of `<PricingPage />`.
+ *
+ * @example
+ * ```tsx
+ * <PricingPage
+ *   renderLimits={(limits) => (
+ *     <LimitsList>
+ *       <LimitsItem>{t('pricing.blocks', { count: limits.maxBlocks })}</LimitsItem>
+ *       <LimitsItem included={limits.canExport}>{t('pricing.dataExport')}</LimitsItem>
+ *     </LimitsList>
+ *   )}
+ * />
+ * ```
+ */
+export function LimitsList({ children }) {
+    const cm = getClassMap();
+    return (_jsx("ul", { className: cm.stack(3), "data-mol-id": "pricing-limits-list", children: children }));
+}
+/**
+ * Single row in a tier's feature list — a check (or em-dash) icon
+ * followed by the row label. Use inside `<LimitsList>`.
+ */
+export function LimitsItem({ children, included = true }) {
+    const cm = getClassMap();
+    return (_jsxs("li", { className: cm.cn(cm.flex({ direction: 'row', align: 'start', gap: 'sm' }), cm.textSize('sm'), !included && cm.textMuted), children: [_jsx(Icon, { name: included ? 'check-circle' : 'minus', size: 18, "aria-hidden": "true", className: included ? cm.textPrimary : cm.textSubtle }), _jsx("span", { children: children })] }));
+}
+/**
+ * Default "anonymous → routes to" path used when a logged-out visitor
+ * clicks an upgrade CTA. Apps can override via the `unauthenticatedRedirect`
+ * prop. `/login` is the convention across flagship templates.
+ */
+const DEFAULT_UNAUTHENTICATED_REDIRECT = '/login';
+/**
+ * Headline font is sourced from the app's theme via the
+ * `--font-headline` CSS variable. Apps that want a serif/display
+ * treatment set this variable in their `theme.css`. Apps that don't
+ * set it inherit the body font (no special headline treatment), which
+ * is the safe default for a generic shared component — we never bake
+ * a specific font family into the shared package.
+ *
+ * The CSS variable fallback chain is intentionally just `inherit` so
+ * the headline picks up whatever the surrounding context uses; apps
+ * that want a custom stack pass `headlineFontFamily` to override
+ * either with a literal string or another `var(--something)` value.
+ */
+const DEFAULT_HEADLINE_FONT = 'var(--font-headline, inherit)';
+/**
+ * Renders the public pricing page. Fetches `/api/billing/tiers` on mount
+ * and lays out one card per tier with the price for the selected period
+ * and a CTA that starts a Stripe Checkout session via
+ * `/api/billing/checkout`. Tiers without a Stripe priceId (e.g. the free
+ * tier or local-dev) render a disabled CTA so users still see the row.
+ *
+ * The highest-priced paid tier is highlighted as "most popular" by
+ * default — the card uses the elevated variant, the header carries a
+ * star badge, and its CTA renders in the primary color. Apps that want
+ * a different tier in the spotlight can pass `popularTierKey` (or
+ * `null` to suppress).
+ *
+ * @param props - Component props (see `PricingPageProps`).
+ * @returns The rendered pricing page.
+ */
+export function PricingPage(props) {
+    const { period = 'month', renderLimits, headingKey = 'billing.pricing.heading', headingDefault = 'Choose your plan', subheadingKey = 'billing.pricing.subheading', subheadingDefault = 'Pick the plan that fits how you work. Upgrade or downgrade any time.', className, unauthenticatedRedirect = DEFAULT_UNAUTHENTICATED_REDIRECT, popularTierKey, headlineFontFamily = DEFAULT_HEADLINE_FONT, } = props;
+    const headlineStyle = headlineFontFamily === null ? undefined : { fontFamily: headlineFontFamily };
+    const cm = getClassMap();
+    const { t } = useTranslation();
+    const auth = useAuth();
+    const { data, loading, error } = usePricingTiers();
+    const { start, loading: starting, error: startError } = useStartCheckout();
+    if (loading) {
+        return (_jsx("section", { className: cm.cn(cm.maxW('xl'), cm.mxAuto, cm.textCenter, cm.sp('py', 16), className), "data-mol-id": "pricing-page", children: _jsx("p", { className: cm.textMuted, children: t('billing.pricing.loading', undefined, { defaultValue: 'Loading plans…' }) }) }));
+    }
+    if (error || !data) {
+        return (_jsx("section", { className: cm.cn(cm.maxW('xl'), cm.mxAuto, cm.textCenter, cm.sp('py', 16), className), "data-mol-id": "pricing-page", children: _jsx("p", { className: cm.formError, children: t('billing.pricing.error', undefined, {
+                    defaultValue: 'Could not load pricing. Try again later.',
+                }) }) }));
+    }
+    const rawTiers = data.data;
+    // Default-pick the popular tier: highest-priced paid tier that has a
+    // real Stripe price id for the active period. Honors `popularTierKey`
+    // override when set (string = use that key; null = disable highlight).
+    const resolvedPopularKey = popularTierKey === null ? null : (popularTierKey ?? autoSelectPopular(rawTiers, period));
+    // Move the popular tier to the visual center of the row. We keep the
+    // server's order otherwise — only the highlighted tier shifts. For odd
+    // tier counts this means index `Math.floor(N/2)`; for 2 tiers we leave
+    // the popular one second so it still flanks the free tier on the right.
+    const tiers = centerPopularTier(rawTiers, resolvedPopularKey);
+    const handleUpgrade = async (priceId) => {
+        if (!priceId)
+            return;
+        // Always fire the POST so the API is the source of truth for auth and
+        // entitlement gating. Short-circuiting on `auth.isAuthenticated` would
+        // produce a "silent button" for anonymous visitors (no network activity,
+        // no observable failure) and bypass the API's 401 contract that e2e
+        // suites rely on. Redirect anonymous visitors only AFTER the POST
+        // resolves (or fails), so the request is always observable.
+        const response = await start(priceId);
+        if (!response) {
+            if (!auth.isAuthenticated && unauthenticatedRedirect && typeof window !== 'undefined') {
+                window.location.assign(unauthenticatedRedirect);
+            }
+            return;
+        }
+        if (response.checkoutUrl) {
+            window.location.assign(response.checkoutUrl);
+        }
+        else if (response.updated) {
+            window.location.reload();
+        }
+    };
+    return (_jsxs("section", { className: cm.cn(cm.maxW('6xl'), cm.mxAuto, cm.sp('px', 6), cm.sp('py', 12), className), "data-mol-id": "pricing-page", children: [_jsxs("header", { className: cm.cn(cm.textCenter, cm.sp('mb', 10)), children: [_jsx("h1", { className: cm.cn(cm.textSize('4xl'), cm.fontWeight('bold'), cm.sp('mb', 3)), style: headlineStyle, "data-mol-id": "pricing-page-heading", children: t(headingKey, undefined, { defaultValue: headingDefault }) }), subheadingKey !== null && (_jsx("p", { className: cm.cn(cm.textSize('lg'), cm.textMuted, cm.maxW('2xl'), cm.mxAuto), "data-mol-id": "pricing-page-subheading", children: t(subheadingKey, undefined, { defaultValue: subheadingDefault }) }))] }), _jsx("div", { className: cm.flex({
+                    direction: 'row',
+                    wrap: 'wrap',
+                    gap: 'lg',
+                    justify: 'center',
+                    align: 'stretch',
+                }), children: tiers.map((tier) => (_jsx(TierCard, { tier: tier, period: period, cm: cm, t: t, renderLimits: renderLimits, onUpgrade: handleUpgrade, starting: starting, popular: tier.key === resolvedPopularKey, headlineStyle: headlineStyle }, tier.key))) }), startError && (_jsx("p", { className: cm.cn(cm.formError, cm.sp('mt', 6), cm.textCenter), role: "alert", children: t('billing.pricing.checkoutError', undefined, {
+                    defaultValue: 'Could not start checkout. Please try again.',
+                }) })), _jsx("p", { className: cm.cn(cm.sp('mt', 10), cm.textCenter, cm.textSize('xs'), cm.textSubtle), "data-mol-id": "pricing-page-reassurance", children: t('billing.pricing.reassurance', undefined, {
+                    defaultValue: 'Cancel anytime · No credit card required to start',
+                }) })] }));
+}
+/**
+ * Renders a single pricing tier card with its price, limits, and upgrade CTA.
+ */
+function TierCard({ tier, period, cm, t, renderLimits, onUpgrade, starting, popular, headlineStyle, }) {
+    const price = tier.prices.find((p) => p.period === period) ?? tier.prices[0];
+    const periodLabel = price?.period
+        ? t(`billing.pricing.period.${price.period}`, undefined, {
+            defaultValue: price.period === 'year' ? 'per year' : 'per month',
+        })
+        : '';
+    void periodLabel;
+    return (_jsx("div", { 
+        // Outer wrapper keeps the popular tier physically larger (taller
+        // + wider) than its neighbors. The "Most popular" tag sits
+        // INSIDE the card at the top-right, matching the Stitch
+        // reference — not floating above the top edge.
+        style: {
+            position: 'relative',
+            width: popular ? '24rem' : '19rem',
+            marginTop: popular ? '-1.5rem' : 0,
+            marginBottom: popular ? '-1.5rem' : 0,
+        }, children: _jsxs("article", { className: cm.cn(
+            // `elevated` removes the default 1px all-sides border so the
+            // popular tier's `borderTPrimary` accent shows ONLY as a top
+            // edge instead of bleeding into a 4-sided primary ring.
+            // Keeps the theme's `bg-surface` card color so cards still
+            // contrast with the page background — `bg-white` blended
+            // away on themes whose page bg is also white.
+            cm.card({ variant: 'elevated' }), cm.flex({ direction: 'col' }), popular && cm.borderTPrimary), style: {
+                position: 'relative',
+                height: '100%',
+                // Generous internal padding matches the Stitch reference's
+                // editorial whitespace — content should never crowd edges.
+                padding: popular ? '3rem 2.5rem 2.5rem' : '2.5rem 2rem',
+                // Strong soft shadow lifts cards off any same-colored page
+                // background. Heavier on the popular tier for emphasis.
+                boxShadow: popular
+                    ? '0 24px 48px -12px rgba(15, 23, 42, 0.18), 0 8px 16px -8px rgba(15, 23, 42, 0.08)'
+                    : '0 12px 24px -8px rgba(15, 23, 42, 0.10), 0 4px 8px -4px rgba(15, 23, 42, 0.06)',
+            }, "data-mol-id": `pricing-tier-${tier.key}`, "data-popular": popular ? 'true' : undefined, children: [popular && (_jsx("span", { className: cm.cn(cm.uppercase, cm.trackingWide, cm.fontWeight('bold'), cm.textSize('xs')), style: {
+                        position: 'absolute',
+                        top: '1rem',
+                        right: '1rem',
+                        backgroundColor: 'var(--color-accent-soft, #ffdf99)',
+                        color: 'var(--color-on-accent-soft, #5a4300)',
+                        padding: '0.25rem 0.6rem',
+                        borderRadius: '999px',
+                        lineHeight: 1.2,
+                        zIndex: 1,
+                    }, "data-mol-id": `pricing-tier-${tier.key}-popular-badge`, children: t('billing.pricing.mostPopular', undefined, { defaultValue: 'Most popular' }) })), _jsxs("header", { className: cm.cardHeader, children: [!popular && (_jsx("p", { className: cm.cn(cm.textSize('xs'), cm.textSubtle, cm.fontWeight('semibold'), cm.uppercase, cm.trackingWide, cm.sp('mb', 2)), "data-mol-id": `pricing-tier-${tier.key}-eyebrow`, children: t('billing.pricing.tierEyebrow', undefined, { defaultValue: 'Tier' }) })), _jsx("h2", { className: cm.cn(cm.textSize('2xl'), cm.italic, cm.fontWeight('semibold'), cm.sp('mb', 4)), style: headlineStyle, children: tier.name }), _jsxs("p", { children: [_jsx("span", { className: cm.cn(cm.textSize('5xl'), cm.fontWeight('bold'), popular && cm.textPrimary), style: headlineStyle, children: price?.price ?? '—' }), tier.perSeat && (_jsxs("span", { className: cm.cn(cm.textSize('sm'), cm.textMuted, cm.fontWeight('normal')), children: [' ', t('billing.pricing.perSeat', undefined, { defaultValue: 'per seat' })] }))] }), _jsxs("p", { className: cm.cn(cm.textSize('xs'), cm.textSubtle, cm.fontWeight('semibold'), cm.uppercase, cm.trackingWide, cm.sp('mt', 2)), children: [t(`billing.pricing.billed.${price?.period ?? 'month'}`, undefined, {
+                                    defaultValue: price?.period === 'year' ? 'Billed annually' : 'Billed monthly',
+                                }), price?.savings && (_jsxs(_Fragment, { children: [' · ', _jsx("span", { className: cm.textSuccess, children: price.savings.toUpperCase() })] }))] })] }), _jsx("div", { className: cm.cn(cm.cardContent, cm.flex1), children: renderLimits ? (renderLimits(tier.limits)) : (_jsx(DefaultLimits, { limits: tier.limits, cm: cm })) }), _jsx("footer", { className: cm.cardFooter, children: _jsx("button", { type: "button", className: cm.cn(cm.button({
+                            variant: popular ? 'solid' : 'outline',
+                            size: 'md',
+                            fullWidth: true,
+                        }), popular && cm.gradientPrimary, cm.uppercase, cm.trackingWide, cm.fontWeight('semibold'), cm.textSize('sm')), 
+                        // Override the cramped default size — `cm.button({size: 'md'})`
+                        // gives `h-[30px] px-2.5` which feels like a tag, not a CTA.
+                        // Real button padding: ~14px vertical, ~20px horizontal.
+                        style: {
+                            height: 'auto',
+                            paddingTop: '0.875rem',
+                            paddingBottom: '0.875rem',
+                            paddingLeft: '1.25rem',
+                            paddingRight: '1.25rem',
+                        }, disabled: !price?.stripePriceId || starting, onClick: () => onUpgrade(price?.stripePriceId ?? null), "data-mol-id": `pricing-cta-${tier.key}`, children: price?.stripePriceId
+                            ? t('billing.pricing.upgradeCta', { tierName: tier.name }, { defaultValue: 'Upgrade to {{tierName}}' })
+                            : t('billing.pricing.currentCta', undefined, { defaultValue: 'Current plan' }) }) })] }) }));
+}
+/**
+ * Default render for a tier's `limits` object — a stacked checklist
+ * with a green check glyph per row. Numbers and booleans render
+ * directly; objects/arrays JSON-stringify. Apps with richer limit
+ * shapes should pass their own `renderLimits` prop to `<PricingPage />`.
+ *
+ * @param props - The component props.
+ * @param props.limits - Tier-specific limits to render.
+ * @param props.cm - Active ClassMap instance.
+ * @returns A `<ul>` of check-prefixed limit rows.
+ */
+function DefaultLimits({ limits, cm }) {
+    if (limits == null || typeof limits !== 'object') {
+        return _jsx(_Fragment, {});
+    }
+    const entries = Object.entries(limits);
+    return (_jsx("ul", { className: cm.stack(2), children: entries.map(([key, value]) => (_jsxs("li", { className: cm.cn(cm.flex({ direction: 'row', align: 'start', gap: 'sm' }), cm.textSize('sm')), children: [_jsx(Icon, { name: "check-circle", size: 16, className: cm.textSuccess, "aria-hidden": "true" }), _jsxs("span", { children: [_jsxs("span", { className: cm.textMuted, children: [humanizeKey(key), ": "] }), _jsx("span", { className: cm.fontWeight('medium'), children: formatLimitValue(value) })] })] }, key))) }));
+}
+/**
+ * Converts a camelCase or snake_case key into a human-readable label (e.g. `maxBlocks` → `Max blocks`).
+ */
+function humanizeKey(key) {
+    // 'maxBlocks' → 'Max blocks'; 'canExport' → 'Can export';
+    // 'max_blocks' → 'Max blocks'. The PricingPage caller can always
+    // override with renderLimits for fully custom labels.
+    const spaced = key
+        .replace(/_/g, ' ')
+        .replace(/([a-z])([A-Z])/g, '$1 $2')
+        .toLowerCase();
+    return spaced.charAt(0).toUpperCase() + spaced.slice(1);
+}
+/**
+ * Formats a raw limit value (boolean, number, string, or object) into a display string.
+ */
+function formatLimitValue(value) {
+    if (typeof value === 'boolean')
+        return value ? '✓' : '—';
+    if (typeof value === 'number') {
+        if (value >= 999_999)
+            return 'Unlimited';
+        return value.toLocaleString();
+    }
+    if (value == null)
+        return '—';
+    if (typeof value === 'string')
+        return value;
+    try {
+        return JSON.stringify(value);
+    }
+    catch (_error) {
+        // JSON.stringify can throw on circular references; String() is always safe.
+        return String(value);
+    }
+}
+/**
+ * Pick the "most popular" tier when the caller hasn't specified one:
+ * the highest-priced paid tier that has a real stripePriceId for the
+ * active period. If nothing qualifies, returns null (no highlight).
+ */
+function autoSelectPopular(tiers, period) {
+    let bestKey = null;
+    let bestCents = -1;
+    for (const tier of tiers) {
+        const price = tier.prices.find((p) => p.period === period) ?? tier.prices[0];
+        if (!price?.stripePriceId)
+            continue;
+        const cents = priceToCents(price.price);
+        if (cents > bestCents) {
+            bestCents = cents;
+            bestKey = tier.key;
+        }
+    }
+    return bestKey;
+}
+/**
+ * Parses a price label string (e.g. `"$12.99/mo"`) into an integer cent value for comparison.
+ */
+function priceToCents(label) {
+    if (!label)
+        return 0;
+    // Accept "$12", "$12.99/mo", "€12,99" — strip currency + suffix, parse the number.
+    const match = label.match(/(\d+(?:[.,]\d+)?)/);
+    if (!match)
+        return 0;
+    return Math.round(Number(match[1].replace(',', '.')) * 100);
+}
+/**
+ * Move the popular tier to the visual center of the row so the
+ * highlighted card flanks the other tiers. Returns a new array with the
+ * popular tier at `Math.floor(N/2)`; if the popular key isn't found, or
+ * is already in that position, the array is returned unchanged.
+ */
+function centerPopularTier(tiers, popularKey) {
+    if (!popularKey || tiers.length < 3)
+        return [...tiers];
+    const targetIdx = Math.floor(tiers.length / 2);
+    const currentIdx = tiers.findIndex((t) => t.key === popularKey);
+    if (currentIdx === -1 || currentIdx === targetIdx)
+        return [...tiers];
+    const next = [...tiers];
+    const [popular] = next.splice(currentIdx, 1);
+    next.splice(targetIdx, 0, popular);
+    return next;
+}

package/dist/hooks.d.ts

@@ -0,0 +1,66 @@
+/**
+ * React hooks for the standard `/billing/*` endpoints.
+ *
+ * These hooks wrap `@molecule/app-react`'s HTTP primitives so callers get
+ * familiar `{ data, loading, error }` ergonomics. The endpoints they hit
+ * are provided server-side by `@molecule/api-entitlements` +
+ * `@molecule/api-payments-stripe` (see
+ * `mlcl/templates/apps/<app>/api/routes/billing.ts` for the routes).
+ *
+ * NOTE on URLs: flagship apps do NOT bond an HTTP client baseURL — each
+ * page-level caller passes the full `/api/...` path explicitly. We match
+ * that convention here so the hooks work in any flagship app whether or
+ * not it later opts into a baseURL-bonded client.
+ *
+ * @module
+ */
+import { type UseHttpResult } from '@molecule/app-react';
+import type { BillingStatus, CancelResponse, CheckoutResponse, PricingTiersResponse } from './types.js';
+/**
+ * Fetch the public pricing data once on mount. Useful inside a
+ * pricing/upgrade page where the tiers are needed before render.
+ *
+ * @template TLimits - Application-specific tier limits shape.
+ * @returns Async-state for the pricing tiers response.
+ */
+export declare function usePricingTiers<TLimits = unknown>(): UseHttpResult<PricingTiersResponse<TLimits>>;
+/**
+ * Fetch the signed-in user's current subscription state once on mount.
+ * Returns 401 from the API when the user is not authenticated; consumers
+ * should treat the absence of `data` as "anonymous → free tier".
+ *
+ * @template TLimits - Application-specific tier limits shape.
+ * @returns Async-state for the user's billing status.
+ */
+export declare function useBillingStatus<TLimits = unknown>(): UseHttpResult<BillingStatus<TLimits>>;
+/** Async-state shape returned by `useStartCheckout` / `useCancelSubscription`. */
+export interface BillingActionState<T> {
+    /** The most recent response from the action, or `null` before the first call. */
+    data: T | null;
+    /** True while a request is in flight. */
+    loading: boolean;
+    /** Last error thrown by the action, or `null` on success. */
+    error: Error | null;
+}
+/**
+ * Start a Stripe Checkout session for a given Stripe price ID. The
+ * returned `start(priceId)` posts to `/api/billing/checkout`; the
+ * response is either `{ checkoutUrl }` (for new subscribers — redirect
+ * the browser) or `{ updated: true }` (for existing subscribers —
+ * refresh the page).
+ *
+ * @returns Async-state plus a `start` function.
+ */
+export declare function useStartCheckout(): BillingActionState<CheckoutResponse> & {
+    start: (priceId: string) => Promise<CheckoutResponse | null>;
+};
+/**
+ * Cancel the user's active subscription at the end of the current
+ * billing period. Returns the response from the bonded payment provider.
+ *
+ * @returns Async-state plus a `cancel` function.
+ */
+export declare function useCancelSubscription(): BillingActionState<CancelResponse> & {
+    cancel: () => Promise<CancelResponse | null>;
+};
+//# sourceMappingURL=hooks.d.ts.map

package/dist/hooks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hooks.d.ts","sourceRoot":"","sources":["../src/hooks.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAIH,OAAO,EAAyB,KAAK,aAAa,EAAE,MAAM,qBAAqB,CAAA;AAE/E,OAAO,KAAK,EACV,aAAa,EACb,cAAc,EACd,gBAAgB,EAChB,oBAAoB,EACrB,MAAM,YAAY,CAAA;AAEnB;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,OAAO,GAAG,OAAO,KAAK,aAAa,CAAC,oBAAoB,CAAC,OAAO,CAAC,CAAC,CAEjG;AAED;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,GAAG,OAAO,KAAK,aAAa,CAAC,aAAa,CAAC,OAAO,CAAC,CAAC,CAE3F;AAED,kFAAkF;AAClF,MAAM,WAAW,kBAAkB,CAAC,CAAC;IACnC,iFAAiF;IACjF,IAAI,EAAE,CAAC,GAAG,IAAI,CAAA;IAEd,yCAAyC;IACzC,OAAO,EAAE,OAAO,CAAA;IAEhB,6DAA6D;IAC7D,KAAK,EAAE,KAAK,GAAG,IAAI,CAAA;CACpB;AAED;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,IAAI,kBAAkB,CAAC,gBAAgB,CAAC,GAAG;IACzE,KAAK,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC,gBAAgB,GAAG,IAAI,CAAC,CAAA;CAC7D,CAyBA;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,IAAI,kBAAkB,CAAC,cAAc,CAAC,GAAG;IAC5E,MAAM,EAAE,MAAM,OAAO,CAAC,cAAc,GAAG,IAAI,CAAC,CAAA;CAC7C,CAsBA"}

package/dist/hooks.js

@@ -0,0 +1,98 @@
+/**
+ * React hooks for the standard `/billing/*` endpoints.
+ *
+ * These hooks wrap `@molecule/app-react`'s HTTP primitives so callers get
+ * familiar `{ data, loading, error }` ergonomics. The endpoints they hit
+ * are provided server-side by `@molecule/api-entitlements` +
+ * `@molecule/api-payments-stripe` (see
+ * `mlcl/templates/apps/<app>/api/routes/billing.ts` for the routes).
+ *
+ * NOTE on URLs: flagship apps do NOT bond an HTTP client baseURL — each
+ * page-level caller passes the full `/api/...` path explicitly. We match
+ * that convention here so the hooks work in any flagship app whether or
+ * not it later opts into a baseURL-bonded client.
+ *
+ * @module
+ */
+import { useCallback, useState } from 'react';
+import { useGet, useHttpClient } from '@molecule/app-react';
+/**
+ * Fetch the public pricing data once on mount. Useful inside a
+ * pricing/upgrade page where the tiers are needed before render.
+ *
+ * @template TLimits - Application-specific tier limits shape.
+ * @returns Async-state for the pricing tiers response.
+ */
+export function usePricingTiers() {
+    return useGet('/api/billing/tiers', { immediate: true });
+}
+/**
+ * Fetch the signed-in user's current subscription state once on mount.
+ * Returns 401 from the API when the user is not authenticated; consumers
+ * should treat the absence of `data` as "anonymous → free tier".
+ *
+ * @template TLimits - Application-specific tier limits shape.
+ * @returns Async-state for the user's billing status.
+ */
+export function useBillingStatus() {
+    return useGet('/api/billing/status', { immediate: true });
+}
+/**
+ * Start a Stripe Checkout session for a given Stripe price ID. The
+ * returned `start(priceId)` posts to `/api/billing/checkout`; the
+ * response is either `{ checkoutUrl }` (for new subscribers — redirect
+ * the browser) or `{ updated: true }` (for existing subscribers —
+ * refresh the page).
+ *
+ * @returns Async-state plus a `start` function.
+ */
+export function useStartCheckout() {
+    const client = useHttpClient();
+    const [state, setState] = useState({
+        data: null,
+        loading: false,
+        error: null,
+    });
+    const start = useCallback(async (priceId) => {
+        setState({ data: null, loading: true, error: null });
+        try {
+            const response = await client.post('/api/billing/checkout', { priceId });
+            setState({ data: response.data, loading: false, error: null });
+            return response.data;
+        }
+        catch (err) {
+            const error = err instanceof Error ? err : new Error(String(err));
+            setState({ data: null, loading: false, error });
+            return null;
+        }
+    }, [client]);
+    return { ...state, start };
+}
+/**
+ * Cancel the user's active subscription at the end of the current
+ * billing period. Returns the response from the bonded payment provider.
+ *
+ * @returns Async-state plus a `cancel` function.
+ */
+export function useCancelSubscription() {
+    const client = useHttpClient();
+    const [state, setState] = useState({
+        data: null,
+        loading: false,
+        error: null,
+    });
+    const cancel = useCallback(async () => {
+        setState({ data: null, loading: true, error: null });
+        try {
+            const response = await client.post('/api/billing/cancel', {});
+            setState({ data: response.data, loading: false, error: null });
+            return response.data;
+        }
+        catch (err) {
+            const error = err instanceof Error ? err : new Error(String(err));
+            setState({ data: null, loading: false, error });
+            return null;
+        }
+    }, [client]);
+    return { ...state, cancel };
+}

package/dist/index.d.ts

@@ -0,0 +1,82 @@
+/**
+ * React pricing page + checkout flow for the molecule.dev billing kit.
+ *
+ * Components:
+ *   `<PricingPage />` — public pricing table that fetches `/api/billing/tiers`
+ *   and posts to `/api/billing/checkout` when the user clicks Upgrade.
+ *
+ *   `<BillingStatusBadge />` — compact account-page status display that
+ *   shows the current tier and offers a cancel-subscription button.
+ *
+ *   `<LimitsList>` / `<LimitsItem>` — building blocks for the
+ *   `renderLimits` prop: a stacked checklist row with check / dash icon,
+ *   e.g. `renderLimits={(l) => (
+ *     <LimitsList>
+ *       <LimitsItem>{l.maxAccounts} accounts</LimitsItem>
+ *       <LimitsItem included={l.canExport}>Data export</LimitsItem>
+ *     </LimitsList>
+ *   )}`
+ *
+ * Hooks:
+ *   `usePricingTiers<TLimits>()`        → `UseHttpResult<PricingTiersResponse<TLimits>>`
+ *   `useBillingStatus<TLimits>()`       → `UseHttpResult<BillingStatus<TLimits>>`
+ *   `useStartCheckout()`                → `{ data, loading, error, start(priceId) }`
+ *   `useCancelSubscription()`           → `{ data, loading, error, cancel() }`
+ *
+ * The API side of this kit lives in `@molecule/api-entitlements` +
+ * `@molecule/api-payments-stripe`. Wire those into your project (any
+ * mlcl flagship template that includes `@molecule/api-entitlements`
+ * already exposes the `/api/billing/*` routes), then drop `<PricingPage />`
+ * onto a `/pricing` route.
+ *
+ * @remarks
+ * **Name collision:** `PricingPage` is also exported by
+ * `@molecule/app-pricing-page-react` (a tier-card grid with a monthly/yearly
+ * toggle driven by `usePricingTiers()`). THIS package's `<PricingPage>` is the
+ * entitlements-kit table with a `renderLimits` prop + compound
+ * `<LimitsList>`/`<LimitsItem>` and a built-in `<BillingStatusBadge>` — import
+ * from `@molecule/app-billing-react` when you are wiring
+ * `@molecule/api-entitlements`. If you import both packages, alias one to avoid
+ * the clash.
+ *
+ * @example
+ * ```tsx
+ * import { PricingPage } from '@molecule/app-billing-react'
+ * import type { PersonalFinanceLimits } from '../tiers'
+ *
+ * const Pricing = () => (
+ *   <PricingPage<PersonalFinanceLimits>
+ *     period="month"
+ *     renderLimits={(l) => (
+ *       <ul>
+ *         <li>{l.maxAccounts} accounts</li>
+ *         <li>{l.maxTransactionsPerMonth} transactions / month</li>
+ *       </ul>
+ *     )}
+ *   />
+ * )
+ * ```
+ *
+ * @e2e
+ * Integration checklist — drive the real UI (live preview, no mocks), adapt
+ * each item to this app's actual screens/flows, and check every box off one
+ * by one. A box you can't check is an integration bug to fix — not a skip:
+ * - [ ] The pricing route renders every tier from `/api/billing/tiers` with name,
+ *   price, and per-tier limits — no empty table, no `undefined` cells.
+ * - [ ] The signed-in user's CURRENT tier is visibly marked (highlighted / "current
+ *   plan") and its Upgrade button is disabled or absent.
+ * - [ ] Clicking Upgrade on another tier posts to `/api/billing/checkout` and the
+ *   page follows the returned checkout handoff (button is not a dead click).
+ * - [ ] `<BillingStatusBadge />` on the account screen shows the live tier, and its
+ *   cancel action updates the shown status after confirmation.
+ * - [ ] A signed-out visitor can still view the public pricing table.
+ * - [ ] If the tiers endpoint fails, the page shows a visible error state — not a
+ *   blank page or spinner forever.
+ *
+ * @module
+ */
+export * from './BillingStatusBadge.js';
+export * from './hooks.js';
+export * from './PricingPage.js';
+export * from './types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4EG;AAEH,cAAc,yBAAyB,CAAA;AACvC,cAAc,YAAY,CAAA;AAC1B,cAAc,kBAAkB,CAAA;AAChC,cAAc,YAAY,CAAA"}

package/dist/index.js

@@ -0,0 +1,81 @@
+/**
+ * React pricing page + checkout flow for the molecule.dev billing kit.
+ *
+ * Components:
+ *   `<PricingPage />` — public pricing table that fetches `/api/billing/tiers`
+ *   and posts to `/api/billing/checkout` when the user clicks Upgrade.
+ *
+ *   `<BillingStatusBadge />` — compact account-page status display that
+ *   shows the current tier and offers a cancel-subscription button.
+ *
+ *   `<LimitsList>` / `<LimitsItem>` — building blocks for the
+ *   `renderLimits` prop: a stacked checklist row with check / dash icon,
+ *   e.g. `renderLimits={(l) => (
+ *     <LimitsList>
+ *       <LimitsItem>{l.maxAccounts} accounts</LimitsItem>
+ *       <LimitsItem included={l.canExport}>Data export</LimitsItem>
+ *     </LimitsList>
+ *   )}`
+ *
+ * Hooks:
+ *   `usePricingTiers<TLimits>()`        → `UseHttpResult<PricingTiersResponse<TLimits>>`
+ *   `useBillingStatus<TLimits>()`       → `UseHttpResult<BillingStatus<TLimits>>`
+ *   `useStartCheckout()`                → `{ data, loading, error, start(priceId) }`
+ *   `useCancelSubscription()`           → `{ data, loading, error, cancel() }`
+ *
+ * The API side of this kit lives in `@molecule/api-entitlements` +
+ * `@molecule/api-payments-stripe`. Wire those into your project (any
+ * mlcl flagship template that includes `@molecule/api-entitlements`
+ * already exposes the `/api/billing/*` routes), then drop `<PricingPage />`
+ * onto a `/pricing` route.
+ *
+ * @remarks
+ * **Name collision:** `PricingPage` is also exported by
+ * `@molecule/app-pricing-page-react` (a tier-card grid with a monthly/yearly
+ * toggle driven by `usePricingTiers()`). THIS package's `<PricingPage>` is the
+ * entitlements-kit table with a `renderLimits` prop + compound
+ * `<LimitsList>`/`<LimitsItem>` and a built-in `<BillingStatusBadge>` — import
+ * from `@molecule/app-billing-react` when you are wiring
+ * `@molecule/api-entitlements`. If you import both packages, alias one to avoid
+ * the clash.
+ *
+ * @example
+ * ```tsx
+ * import { PricingPage } from '@molecule/app-billing-react'
+ * import type { PersonalFinanceLimits } from '../tiers'
+ *
+ * const Pricing = () => (
+ *   <PricingPage<PersonalFinanceLimits>
+ *     period="month"
+ *     renderLimits={(l) => (
+ *       <ul>
+ *         <li>{l.maxAccounts} accounts</li>
+ *         <li>{l.maxTransactionsPerMonth} transactions / month</li>
+ *       </ul>
+ *     )}
+ *   />
+ * )
+ * ```
+ *
+ * @e2e
+ * Integration checklist — drive the real UI (live preview, no mocks), adapt
+ * each item to this app's actual screens/flows, and check every box off one
+ * by one. A box you can't check is an integration bug to fix — not a skip:
+ * - [ ] The pricing route renders every tier from `/api/billing/tiers` with name,
+ *   price, and per-tier limits — no empty table, no `undefined` cells.
+ * - [ ] The signed-in user's CURRENT tier is visibly marked (highlighted / "current
+ *   plan") and its Upgrade button is disabled or absent.
+ * - [ ] Clicking Upgrade on another tier posts to `/api/billing/checkout` and the
+ *   page follows the returned checkout handoff (button is not a dead click).
+ * - [ ] `<BillingStatusBadge />` on the account screen shows the live tier, and its
+ *   cancel action updates the shown status after confirmation.
+ * - [ ] A signed-out visitor can still view the public pricing table.
+ * - [ ] If the tiers endpoint fails, the page shows a visible error state — not a
+ *   blank page or spinner forever.
+ *
+ * @module
+ */
+export * from './BillingStatusBadge.js';
+export * from './hooks.js';
+export * from './PricingPage.js';
+export * from './types.js';

package/dist/types.d.ts

@@ -0,0 +1,90 @@
+/**
+ * Type definitions mirroring the API-side billing endpoint contracts.
+ *
+ * These types match the JSON shapes returned by `@molecule/api-entitlements`
+ * + `@molecule/api-payments-stripe` when an app exposes the standard billing
+ * routes:
+ *
+ * - `GET  /api/billing/tiers`   → `{ data: PricingTierEntry[] }`
+ * - `GET  /api/billing/status`  → `BillingStatus`
+ * - `POST /api/billing/checkout` body: `{ priceId: string }`
+ *                                response: `{ checkoutUrl }` | `{ updated, subscription }`
+ * - `POST /api/billing/cancel`  → `{ canceled: true }`
+ *
+ * @module
+ */
+/**
+ * One billing period offered for a tier — typically `month` or `year` —
+ * with the human-readable price string and the Stripe price ID. The price
+ * ID may be `null` for the free tier (no Stripe product).
+ */
+export interface PricingTierPrice {
+    /** Billing cadence. */
+    period: 'month' | 'year';
+    /** Display string (e.g. `'$19/mo'`, `'$190/yr'`, `'$0'`). */
+    price: string;
+    /**
+     * Stripe Price ID used as the line item when the user clicks Upgrade.
+     * `null` for free tiers and during local dev when env vars are unset.
+     */
+    stripePriceId: string | null;
+    /** Optional savings tag on yearly variants (e.g. `'2 months free'`). */
+    savings?: string;
+}
+/**
+ * One row of the public pricing table. Apps can declare any number of
+ * `period` variants per tier (typically a `month` and `year` pair).
+ */
+export interface PricingTierEntry<TLimits = unknown> {
+    /** Stable slug used as a row key (`'free'`, `'pro'`, `'team'`). */
+    key: string;
+    /** Display name shown in the page heading and CTA. */
+    name: string;
+    /** Price variants for the tier. Order is presentation order. */
+    prices: PricingTierPrice[];
+    /** Tier-specific limits — render any/all of these on the comparison row. */
+    limits: TLimits;
+    /** Whether the tier is billed per seat (rendered as a footnote). */
+    perSeat?: boolean;
+}
+/** Response envelope for `GET /api/billing/tiers`. */
+export interface PricingTiersResponse<TLimits = unknown> {
+    /** Tiers ordered as the API returns them (typically free → pro → team). */
+    data: PricingTierEntry<TLimits>[];
+}
+/**
+ * Snapshot of the signed-in user's current billing state. Returned by
+ * `GET /api/billing/status` once the user is authenticated.
+ */
+export interface BillingStatus<TLimits = unknown> {
+    /** The user's `users.planKey` (`'free'`, `'stripeMonthly'`, etc.). */
+    planKey: string;
+    /** Tier category — `'free'`, `'pro'`, `'team'`, or any app-defined extension. */
+    category: string;
+    /** Display name (matches `PricingTierEntry.name` for the active tier). */
+    name: string;
+    /** Tier-specific limits the user is currently entitled to. */
+    limits: TLimits;
+    /** True when the user is on the registry default (free) tier. */
+    isFree: boolean;
+}
+/** Response from `POST /api/billing/checkout`. Either `checkoutUrl` or `updated` is set. */
+export interface CheckoutResponse {
+    /** Stripe Checkout URL — set when the user has no active subscription yet. */
+    checkoutUrl?: string;
+    /** True when the user already had a subscription that was updated in place. */
+    updated?: boolean;
+    /** Updated subscription metadata (only when `updated === true`). */
+    subscription?: {
+        expiresAt?: string;
+        autoRenews?: boolean;
+    };
+}
+/** Response from `POST /api/billing/cancel`. */
+export interface CancelResponse {
+    /** True when the cancellation request was accepted. */
+    canceled?: boolean;
+    /** Localized error message when cancellation failed. */
+    error?: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH;;;;GAIG;AACH,MAAM,WAAW,gBAAgB;IAC/B,uBAAuB;IACvB,MAAM,EAAE,OAAO,GAAG,MAAM,CAAA;IAExB,6DAA6D;IAC7D,KAAK,EAAE,MAAM,CAAA;IAEb;;;OAGG;IACH,aAAa,EAAE,MAAM,GAAG,IAAI,CAAA;IAE5B,wEAAwE;IACxE,OAAO,CAAC,EAAE,MAAM,CAAA;CACjB;AAED;;;GAGG;AACH,MAAM,WAAW,gBAAgB,CAAC,OAAO,GAAG,OAAO;IACjD,mEAAmE;IACnE,GAAG,EAAE,MAAM,CAAA;IAEX,sDAAsD;IACtD,IAAI,EAAE,MAAM,CAAA;IAEZ,gEAAgE;IAChE,MAAM,EAAE,gBAAgB,EAAE,CAAA;IAE1B,4EAA4E;IAC5E,MAAM,EAAE,OAAO,CAAA;IAEf,oEAAoE;IACpE,OAAO,CAAC,EAAE,OAAO,CAAA;CAClB;AAED,sDAAsD;AACtD,MAAM,WAAW,oBAAoB,CAAC,OAAO,GAAG,OAAO;IACrD,2EAA2E;IAC3E,IAAI,EAAE,gBAAgB,CAAC,OAAO,CAAC,EAAE,CAAA;CAClC;AAED;;;GAGG;AACH,MAAM,WAAW,aAAa,CAAC,OAAO,GAAG,OAAO;IAC9C,sEAAsE;IACtE,OAAO,EAAE,MAAM,CAAA;IAEf,iFAAiF;IACjF,QAAQ,EAAE,MAAM,CAAA;IAEhB,0EAA0E;IAC1E,IAAI,EAAE,MAAM,CAAA;IAEZ,8DAA8D;IAC9D,MAAM,EAAE,OAAO,CAAA;IAEf,iEAAiE;IACjE,MAAM,EAAE,OAAO,CAAA;CAChB;AAED,4FAA4F;AAC5F,MAAM,WAAW,gBAAgB;IAC/B,8EAA8E;IAC9E,WAAW,CAAC,EAAE,MAAM,CAAA;IAEpB,+EAA+E;IAC/E,OAAO,CAAC,EAAE,OAAO,CAAA;IAEjB,oEAAoE;IACpE,YAAY,CAAC,EAAE;QACb,SAAS,CAAC,EAAE,MAAM,CAAA;QAClB,UAAU,CAAC,EAAE,OAAO,CAAA;KACrB,CAAA;CACF;AAED,gDAAgD;AAChD,MAAM,WAAW,cAAc;IAC7B,uDAAuD;IACvD,QAAQ,CAAC,EAAE,OAAO,CAAA;IAElB,wDAAwD;IACxD,KAAK,CAAC,EAAE,MAAM,CAAA;CACf"}

package/dist/types.js

@@ -0,0 +1,16 @@
+/**
+ * Type definitions mirroring the API-side billing endpoint contracts.
+ *
+ * These types match the JSON shapes returned by `@molecule/api-entitlements`
+ * + `@molecule/api-payments-stripe` when an app exposes the standard billing
+ * routes:
+ *
+ * - `GET  /api/billing/tiers`   → `{ data: PricingTierEntry[] }`
+ * - `GET  /api/billing/status`  → `BillingStatus`
+ * - `POST /api/billing/checkout` body: `{ priceId: string }`
+ *                                response: `{ checkoutUrl }` | `{ updated, subscription }`
+ * - `POST /api/billing/cancel`  → `{ canceled: true }`
+ *
+ * @module
+ */
+export {};

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@molecule/app-billing-react",
+  "version": "1.0.0",
+  "description": "React pricing page + checkout flow that consumes /api/billing/* (provided by @molecule/api-entitlements + @molecule/api-payments-stripe)",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "keywords": [
+    "molecule",
+    "billing",
+    "subscriptions",
+    "stripe",
+    "react"
+  ],
+  "license": "Apache-2.0",
+  "peerDependencies": {
+    "@molecule/app-http": "^1.0.0",
+    "@molecule/app-react": "^1.0.0",
+    "@molecule/app-ui": "^1.0.0",
+    "@molecule/app-ui-react": "^1.0.0",
+    "react": "^18.0.0 || ^19.0.0"
+  },
+  "devDependencies": {
+    "@molecule/app-http": "1.0.0",
+    "@molecule/app-react": "1.0.0",
+    "@molecule/app-ui": "1.0.0",
+    "@molecule/app-ui-react": "1.0.0",
+    "@types/node": "26.1.2",
+    "@types/react": "19.2.17",
+    "react": "19.2.8",
+    "typescript": "6.0.3",
+    "vitest": "4.1.10"
+  }
+}