@cosmoops/connect-sdk 0.1.0

package/dist/esm/client/components/plans-page.js

@@ -0,0 +1,36 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { ConnectPlans } from "./plans.js";
+import { ConnectReadinessBanner } from "./readiness.js";
+import { ConnectSubscriptionCard } from "./subscription.js";
+import { useConnect } from "../provider.js";
+import { ConnectLoginButton } from "./auth-buttons.js";
+/**
+ * A complete `/plans` page, assembled from the pieces so the host app's route
+ * file is one line:
+ *
+ * ```tsx
+ * // app/plans/page.tsx
+ * "use client";
+ * export { ConnectPlansPage as default } from "@cosmoops/connect-sdk/client";
+ * ```
+ *
+ * The assembly is the value here, not the layout. Three things have to be on
+ * this page and are easy to leave off:
+ *
+ * 1. **The readiness banner, above the grid.** A workspace that still needs
+ *    KYC can press Subscribe all day and be refused at the last step. Saying so
+ *    before they pick is the difference between a page that works and one that
+ *    ends in a rejected charge.
+ * 2. **What they're on now**, so "Upgrade" on a card has something to mean.
+ * 3. **A signed-out state that is a login button**, not an empty grid - the
+ *    catalogue reads through the bridge, which needs a session.
+ *
+ * Every prop `ConnectPlans` takes passes straight through, and each piece is
+ * exported on its own for an app that wants a different arrangement.
+ */
+export function ConnectPlansPage({ title = "Plans", description = "Pick the plan that fits. Change or cancel it whenever you like.", showCurrentSubscription = true, ...plansProps }) {
+    const { session, isLoading } = useConnect();
+    const signedOut = !isLoading && !session?.user;
+    return (_jsxs("div", { className: "mx-auto flex w-full max-w-5xl flex-col gap-6 px-4 py-8", children: [_jsxs("div", { children: [_jsx("h1", { className: "text-2xl font-semibold text-foreground", children: title }), _jsx("p", { className: "text-muted", children: description })] }), signedOut ? (_jsxs("div", { className: "flex flex-col items-start gap-3", children: [_jsx("p", { className: "text-sm text-muted", children: "Sign in to see your plan options and what you're on today." }), _jsx(ConnectLoginButton, {})] })) : (_jsxs(_Fragment, { children: [_jsx(ConnectReadinessBanner, {}), showCurrentSubscription && _jsx(ConnectSubscriptionCard, {}), _jsx(ConnectPlans, { ...plansProps })] }))] }));
+}

package/dist/esm/client/components/plans.js

@@ -0,0 +1,209 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Button, Card, Chip, Input, Skeleton, Switch } from "@heroui/react";
+import { Check, CheckCircle2, ExternalLink, Loader2, Sparkles, Tag } from "lucide-react";
+import { useMemo, useState } from "react";
+import { useConnect, useConnectEntitlements, useConnectPlans } from "../provider.js";
+import { buildCancelUrl, buildCheckoutUrl, useConnectCheckout, } from "../use-checkout.js";
+import { ConnectSubscribeDialog } from "./subscribe-dialog.js";
+import { ACTION_LABEL, discountLabel, formatPrice, groupPlansByTier, resolveAction, } from "./plan-pricing.js";
+/**
+ * The plan table: monthly/annual toggle, features, add-ons, the discount
+ * actually in effect, and the subscribe / upgrade / downgrade flows.
+ *
+ * ## Where the flow runs, and where it finishes
+ *
+ * The *flow* is here: picking a plan, seeing what it costs with GST, being
+ * told what happens to the cycle you are part-way through, and confirming.
+ * The *payment* is not, and that is deliberate. A plan change is not one
+ * write - it re-runs the readiness gates, prices proration against
+ * accumulated credit, re-checks the RBI mandate ceiling for the new amount,
+ * and issues a GST invoice. Connect owns that sequence end to end; a
+ * partner-side "change plan" call would be a second implementation of it
+ * that drifts. It would also mean a browser holding the partner's
+ * credentials could move money, which is the one thing the bridge exists to
+ * prevent.
+ *
+ * So confirming opens Connect - on the *exact* confirmation screen for the
+ * plan just picked, via an intercepted parallel route, not a catalogue the
+ * customer has to search again - and this component watches `/entitlements`
+ * until the change lands, then repaints itself. See `useConnectCheckout`.
+ *
+ * Coupon codes work the same way: the field carries the code into Connect's
+ * checkout, where it is validated and applied against the real cart. Anything
+ * this component claimed about a code would be a guess it cannot honour.
+ */
+export function ConnectPlans({ planIds, hideCoupon = false, className }) {
+    const { appUrl, session } = useConnect();
+    const { data: catalog, isLoading: plansLoading, error } = useConnectPlans();
+    const { data: entitlements, isLoading: entitlementsLoading } = useConnectEntitlements();
+    const checkout = useConnectCheckout();
+    const [annual, setAnnual] = useState(false);
+    const [coupon, setCoupon] = useState("");
+    /** The plan under review in the confirmation dialog, or `null` when it is closed. */
+    const [pending, setPending] = useState(null);
+    const subscription = entitlements?.subscription ?? null;
+    const serviceId = subscription?.serviceId ?? null;
+    const allPlans = useMemo(() => {
+        const plans = catalog?.plans ?? [];
+        if (!planIds)
+            return plans;
+        return planIds.map((id) => plans.find((plan) => plan.id === id)).filter((plan) => !!plan);
+    }, [catalog?.plans, planIds]);
+    // One card per *tier*, with the toggle choosing a price inside each card.
+    // The grid used to filter the flat plan list down to the toggled interval,
+    // which meant a tier sold monthly-only disappeared the moment a customer
+    // looked at annual pricing - and an all-annual catalog rendered nothing at
+    // all, since the toggle starts on monthly.
+    const tiers = useMemo(() => groupPlansByTier(allPlans), [allPlans]);
+    const hasAnnual = tiers.some((tier) => tier.annual !== null);
+    const hasMonthly = tiers.some((tier) => tier.monthly !== null);
+    // Derived, not stored: a catalog with no monthly plans has to open on annual,
+    // and deriving it here keeps that correct from the first paint without an
+    // effect that would flash the empty state first.
+    const showAnnual = hasMonthly ? annual : true;
+    // "Up to", because each tier discounts its annual plan by its own amount -
+    // the badge used to quote one figure computed from whichever monthly and
+    // annual plan happened to come first in the response, which were usually
+    // different tiers entirely.
+    const bestSaving = tiers.reduce((best, tier) => tier.annualSavingPercent !== null && (best === null || tier.annualSavingPercent > best)
+        ? tier.annualSavingPercent
+        : best, null);
+    /**
+     * Hands off to Connect and starts watching for the result.
+     *
+     * The settled test is "the live plan is now the one we sent them to
+     * change to" - the same test for a first subscribe and for a plan change,
+     * and true in both cases the moment Connect writes the row. It does *not*
+     * wait for `hasActiveSubscription`: on the paid path the subscription is
+     * created in `"created"` and only flips to active when the payment webhook
+     * lands, which can be minutes later. Holding a customer on a spinner until
+     * then would misreport a completed checkout as an abandoned one.
+     */
+    function startCheckout(plan) {
+        if (!serviceId)
+            return;
+        checkout.start({
+            url: buildCheckoutUrl({
+                appUrl,
+                serviceId,
+                planId: plan.id,
+                subscriptionId: subscription?.subscription?.id ?? null,
+                coupon,
+            }),
+            isSettled: (next) => next.subscription.plan?.id === plan.id,
+        });
+        setPending(null);
+    }
+    if (plansLoading || entitlementsLoading) {
+        return (_jsx("div", { className: `grid gap-4 sm:grid-cols-2 lg:grid-cols-3 ${className ?? ""}`, children: Array.from({ length: 3 }, (_, index) => (_jsx(Skeleton, { className: "h-80 rounded-xl" }, index))) }));
+    }
+    if (!session?.user) {
+        return _jsx("p", { className: "text-sm text-muted", children: "Sign in to see your plan options." });
+    }
+    if (error) {
+        return _jsx("p", { className: "text-sm text-danger", children: "Could not load plans." });
+    }
+    return (_jsxs("div", { className: `flex flex-col gap-6 ${className ?? ""}`, children: [_jsxs("div", { className: "flex flex-wrap items-center justify-between gap-4", children: [hasAnnual && hasMonthly && (_jsxs("div", { className: "flex items-center gap-3", children: [_jsx("span", { className: showAnnual ? "text-sm text-muted" : "text-sm font-medium text-foreground", children: "Monthly" }), _jsx(Switch, { "aria-label": "Bill annually", isSelected: showAnnual, onChange: setAnnual, children: _jsx(Switch.Content, { children: _jsx(Switch.Control, { children: _jsx(Switch.Thumb, {}) }) }) }), _jsx("span", { className: showAnnual ? "text-sm font-medium text-foreground" : "text-sm text-muted", children: "Annual" }), bestSaving !== null && (_jsxs(Chip, { className: "bg-accent-soft text-accent", children: ["Save up to ", bestSaving, "%"] }))] })), !hideCoupon && (_jsxs("div", { className: "flex items-center gap-2", children: [_jsx(Tag, { className: "size-4 text-muted", "aria-hidden": "true" }), _jsx(Input, { "aria-label": "Coupon code", placeholder: "Coupon code", value: coupon, onChange: (event) => setCoupon(event.target.value.toUpperCase()), className: "w-40" })] }))] }), subscription?.subscription?.appliedDiscount && (_jsxs("div", { className: "flex items-center gap-2 rounded-lg bg-accent-soft px-3 py-2 text-sm text-accent", children: [_jsx(Sparkles, { className: "size-4 shrink-0", "aria-hidden": "true" }), _jsxs("span", { children: [discountLabel(subscription.subscription.appliedDiscount), subscription.subscription.appliedDiscount.code
+                                ? ` - code ${subscription.subscription.appliedDiscount.code}`
+                                : ""] })] })), _jsx(ConnectCheckoutStatusRow, { checkout: checkout }), _jsx("div", { className: "grid gap-4 sm:grid-cols-2 lg:grid-cols-3", children: tiers.map((tier) => {
+                    // The price point this card is showing. A tier missing the toggled
+                    // cadence falls back to the one it does sell rather than dropping
+                    // out of the grid, and says so under the price.
+                    const plan = pickTierPlan(tier, showAnnual);
+                    if (!plan)
+                        return null;
+                    const action = resolveAction(plan, subscription);
+                    // "Current" belongs to the tier, not just the exact price point: an
+                    // org on Growth annual looking at monthly pricing is still on the
+                    // Growth tier, and marking only the row it literally subscribes to
+                    // would leave its own card unmarked half the time.
+                    const isCurrentTier = subscription?.plan != null &&
+                        (tier.monthly?.id === subscription.plan.id || tier.annual?.id === subscription.plan.id);
+                    const isCurrent = action === "current";
+                    const cadenceUnavailable = showAnnual ? tier.annual === null : tier.monthly === null;
+                    return (_jsxs(Card, { className: isCurrentTier ? "border-accent" : undefined, children: [_jsxs(Card.Header, { children: [_jsxs("div", { className: "flex items-start justify-between gap-2", children: [_jsx(Card.Title, { children: tier.name }), _jsxs("div", { className: "flex shrink-0 items-center gap-1.5", children: [tier.annualSavingPercent !== null && showAnnual && (_jsxs(Chip, { className: "bg-accent-soft text-accent", children: ["Save ", tier.annualSavingPercent, "%"] })), isCurrentTier && _jsx(Chip, { className: "bg-accent-soft text-accent", children: "Current" })] })] }), tier.description && _jsx(Card.Description, { children: tier.description })] }), _jsxs(Card.Content, { className: "flex flex-col gap-4", children: [_jsxs("div", { children: [_jsx("span", { className: "text-2xl font-semibold text-foreground", children: formatPrice(plan.price) }), _jsxs("span", { className: "text-sm text-muted", children: ["/", plan.billingInterval === "annual" ? "year" : "month"] }), _jsxs("p", { className: "mt-1 text-xs text-muted", children: ["+", plan.gstRate, "% GST"] }), cadenceUnavailable && (_jsxs("p", { className: "mt-1 text-xs text-muted", children: ["Only sold ", plan.billingInterval === "annual" ? "annually" : "monthly", "."] }))] }), plan.trialDays ? (_jsxs("p", { className: "text-xs font-medium text-accent", children: [plan.trialDays, "-day free trial"] })) : null, plan.features.length > 0 && (_jsx("ul", { className: "flex flex-col gap-1.5", children: plan.features.map((feature) => (
+                                        // `name`, not `key` - the key is an identifier
+                                        // ("campaign-module"), and printing it here is what this
+                                        // card used to do. The description rides along as a
+                                        // title so a feature that needs explaining can have one
+                                        // without a second line in every card.
+                                        _jsxs("li", { className: "flex items-start gap-2 text-sm text-foreground", title: feature.description || undefined, children: [_jsx(Check, { className: "mt-0.5 size-4 shrink-0 text-accent", "aria-hidden": "true" }), _jsx("span", { children: feature.name })] }, feature.key))) })), plan.addons.length > 0 && (_jsxs("div", { className: "flex flex-col gap-1.5 border-t border-separator pt-3", children: [_jsx("p", { className: "text-xs font-medium uppercase tracking-wide text-muted", children: "Add-ons" }), plan.addons.map((addon) => (_jsxs("div", { className: "flex items-baseline justify-between gap-2 text-sm", children: [_jsxs("span", { className: "text-foreground", children: [addon.name, addon.consumable && (_jsxs("span", { className: "text-muted", children: [" ", "- ", addon.consumable.includedPerCycle.toLocaleString("en-IN"), " ", addon.consumable.unit, "/cycle"] }))] }), _jsx("span", { className: "shrink-0 text-muted", children: formatPrice(addon.price) })] }, addon.id)))] })), _jsxs("p", { className: "text-xs text-muted", children: [plan.seats.model === "unlimited" && "Unlimited seats", plan.seats.model === "fixed" && `${plan.seats.included} seats included`, plan.seats.model === "per-seat" &&
+                                                `${plan.seats.included ?? 0} seats included, then ${formatPrice(plan.seats.pricePerExtraSeat ?? 0)} each`] })] }), _jsx(Card.Footer, { children: _jsxs(Button, { className: "w-full", variant: action === "upgrade" || action === "subscribe" || action === "switch-to-annual"
+                                        ? "primary"
+                                        : "secondary", 
+                                    // Disabled while a hand-off is in flight, not just on the
+                                    // card that started it: the org has one subscription per
+                                    // service, so a second checkout opened against a different
+                                    // plan would race the first and one of them would be
+                                    // rejected on arrival.
+                                    isDisabled: isCurrent || checkout.status === "waiting", onPress: () => setPending({ plan, action }), children: [ACTION_LABEL[action], !isCurrent && _jsx(ExternalLink, { className: "size-3.5" })] }) })] }, tier.planGroup));
+                }) }), subscription?.subscription && (_jsx(ConnectUnsubscribeRow, { subscription: subscription.subscription, appUrl: appUrl, checkout: checkout })), _jsx(ConnectSubscribeDialog, { plan: pending?.plan ?? null, action: pending?.action ?? "subscribe", current: subscription, coupon: hideCoupon ? undefined : coupon, onClose: () => setPending(null), onConfirm: () => pending && startCheckout(pending.plan) })] }));
+}
+/**
+ * What the page says while the customer is off in Connect, and after.
+ *
+ * Worth its own row rather than a spinner on the button that opened it: the
+ * customer is looking at a different window, and what they need on returning
+ * is a plain statement of whether it worked - including the case where they
+ * came back having changed their mind, which is not an error and must not
+ * read as one.
+ */
+function ConnectCheckoutStatusRow({ checkout, }) {
+    if (checkout.status === "idle")
+        return null;
+    if (checkout.status === "waiting") {
+        return (_jsxs("div", { className: "flex items-center gap-2 rounded-lg border border-separator px-3 py-2 text-sm text-muted", children: [_jsx(Loader2, { className: "size-4 shrink-0 animate-spin", "aria-hidden": "true" }), _jsx("span", { children: "Finish up in the Connect window. This page updates on its own." })] }));
+    }
+    if (checkout.status === "completed") {
+        return (_jsxs("div", { className: "flex items-center justify-between gap-3 rounded-lg bg-accent-soft px-3 py-2 text-sm text-accent", children: [_jsxs("span", { className: "flex items-center gap-2", children: [_jsx(CheckCircle2, { className: "size-4 shrink-0", "aria-hidden": "true" }), "Your plan is updated."] }), _jsx(Button, { variant: "tertiary", onPress: checkout.reset, children: "Dismiss" })] }));
+    }
+    // `blocked` and `abandoned` share a row: both mean nothing changed, and both
+    // are fixed by going to the same URL - so offer it rather than explaining.
+    return (_jsxs("div", { className: "flex flex-wrap items-center justify-between gap-3 rounded-lg border border-separator px-3 py-2 text-sm text-muted", children: [_jsx("span", { children: checkout.status === "blocked"
+                    ? "Your browser blocked the Connect window."
+                    : "Nothing changed - the Connect window closed before it was finished." }), _jsxs("div", { className: "flex items-center gap-2", children: [checkout.url && (_jsxs(Button, { variant: "secondary", onPress: () => window.open(checkout.url, "_blank", "noopener,noreferrer"), children: ["Open Connect", _jsx(ExternalLink, { className: "size-3.5" })] })), _jsx(Button, { variant: "tertiary", onPress: checkout.reset, children: "Dismiss" })] })] }));
+}
+/**
+ * Cancellation, kept out of the plan grid and stated plainly.
+ *
+ * Runs through the same hand-off as the plan actions above - Connect's
+ * `/billing/subscriptions/{id}/cancel` modal - rather than dropping the
+ * customer on the whole billing page to find the button themselves. It is
+ * still Connect that confirms it: the effective date and what happens to a
+ * part-used cycle both have to be shown before anyone commits, and only
+ * Connect knows them.
+ *
+ * **A subscription already cancelling gets a statement, not a button.** It used
+ * to offer "Resume subscription", which was a promise nothing could keep -
+ * Connect has no uncancel path at all, so the button deep-linked to a page
+ * showing a static "Cancels on ..." chip and no way to act on it. Saying what
+ * will happen, and offering the one thing that does work, is the honest
+ * version.
+ */
+function ConnectUnsubscribeRow({ subscription, appUrl, checkout, }) {
+    const endsOn = subscription.currentBillingCycle?.endDate;
+    if (subscription.cancelAtPeriodEnd) {
+        return (_jsxs("div", { className: "flex flex-wrap items-center justify-between gap-3 border-t border-separator pt-4", children: [_jsxs("p", { className: "text-sm text-muted", children: ["Cancels", endsOn ? ` on ${new Date(endsOn).toLocaleDateString()}` : " at the end of this cycle", ". You keep access until then."] }), _jsxs(Button, { variant: "tertiary", onPress: () => window.open(`${appUrl}/billing/subscriptions/${subscription.id}`, "_blank", "noopener,noreferrer"), children: ["View on Connect", _jsx(ExternalLink, { className: "size-3.5" })] })] }));
+    }
+    return (_jsxs("div", { className: "flex flex-wrap items-center justify-between gap-3 border-t border-separator pt-4", children: [_jsx("p", { className: "text-sm text-muted", children: "Cancel any time. Access continues to the end of the paid cycle." }), _jsxs(Button, { variant: "tertiary", className: "text-danger", isDisabled: checkout.status === "waiting", onPress: () => checkout.start({
+                    url: buildCancelUrl({ appUrl, subscriptionId: subscription.id }),
+                    // A paused subscription cancels outright (`status` goes to
+                    // `"cancelled"`); an active one is deferred to the cycle end
+                    // (`cancelAtPeriodEnd`). Either is the change being waited on.
+                    isSettled: (next) => next.subscription.subscription?.cancelAtPeriodEnd === true ||
+                        next.subscription.subscription?.status === "cancelled" ||
+                        next.subscription.subscription === null,
+                }), children: ["Cancel subscription", _jsx(ExternalLink, { className: "size-3.5" })] })] }));
+}
+/**
+ * Which of a tier's price points to show for the toggled cadence.
+ *
+ * Falls back to the other cadence rather than rendering nothing: a tier sold
+ * monthly-only is a real thing (a free or entry plan usually is), and hiding
+ * it while a customer looks at annual pricing loses them an option that is
+ * still available to buy.
+ */
+function pickTierPlan(tier, showAnnual) {
+    return showAnnual ? (tier.annual ?? tier.monthly) : (tier.monthly ?? tier.annual);
+}

package/dist/esm/client/components/readiness.js

@@ -0,0 +1,113 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { Button, Card } from "@heroui/react";
+import { AlertTriangle, ExternalLink, Info, Loader2 } from "lucide-react";
+import { blockingBlockers } from "../../helpers.js";
+import { useConnect, useConnectEntitlements } from "../provider.js";
+/**
+ * Codes that mean "somebody at Connect is looking at it" - there is no action
+ * for the customer to take, so these get an informational treatment and no
+ * button, even though the server may still hand back a `resolveUrl`.
+ */
+const IN_PROGRESS_CODES = new Set([
+    "verification_pending",
+    "onboarding_approval_pending",
+]);
+/** Codes worth a more specific call to action than a generic "Resolve". */
+const ACTION_LABELS = {
+    subscription_missing: "Choose a plan",
+    subscription_inactive: "Fix subscription",
+    payment_method_missing: "Add a payment method",
+    verification_required: "Start verification",
+    verification_rejected: "Review verification",
+    verification_expired: "Renew verification",
+    seat_limit_reached: "Manage seats",
+};
+function actionLabel(blocker) {
+    return ACTION_LABELS[blocker.code] ?? "Resolve on Connect";
+}
+/**
+ * Every gate between this workspace and your service, with the way out of each.
+ *
+ * This is the component that keeps a blocked customer from staring at a broken
+ * app. `getReadiness` resolves subscription state, KYC/KYB, a chargeable
+ * payment method and seat headroom in one call, and **each blocker carries a
+ * `resolveUrl` into the exact Connect screen that fixes it** - so being blocked
+ * comes with somewhere to go rather than a refusal.
+ *
+ * Render it high on any page your service gates. It draws nothing at all when
+ * the workspace is ready, so it is safe to leave mounted permanently.
+ *
+ * Two deliberate refusals:
+ *
+ * - **Unrecognised codes are still shown, and still treated as blocking.**
+ *   Connect adds codes without a major version (see `ReadinessBlockerCode`), so
+ *   a switch that only knew today's codes would silently drop tomorrow's - the
+ *   one failure mode where a customer is locked out with no explanation.
+ * - **`message` is rendered, never parsed.** It is human-facing and subject to
+ *   rewording; branching on its text would break on a copy edit.
+ */
+export function ConnectReadinessBanner({ includeAdvisory = false, hideWhenReady = true, className, }) {
+    const { session } = useConnect();
+    const { data, isLoading } = useConnectEntitlements();
+    // Signed out is not "blocked" - it is a different question, and answering it
+    // here would put a verification banner in front of a login button.
+    if (!session?.user)
+        return null;
+    if (isLoading) {
+        return (_jsxs("div", { className: `flex items-center gap-2 text-sm text-muted ${className ?? ""}`, children: [_jsx(Loader2, { className: "size-4 animate-spin", "aria-hidden": "true" }), "Checking your workspace\u2026"] }));
+    }
+    if (!data)
+        return null;
+    const blockers = includeAdvisory ? data.readiness.readiness.blockers : blockingBlockers(data.readiness);
+    if (blockers.length === 0)
+        return hideWhenReady ? null : _jsx(ReadyRow, { className: className });
+    return (_jsx("div", { className: `flex flex-col gap-2 ${className ?? ""}`, role: "status", children: blockers.map((blocker) => (_jsx(BlockerRow, { blocker: blocker }, `${blocker.code}-${blocker.message}`))) }));
+}
+function BlockerRow({ blocker }) {
+    const inProgress = IN_PROGRESS_CODES.has(blocker.code);
+    const isBlocking = blocker.severity === "blocking";
+    return (_jsxs("div", { className: `flex flex-wrap items-center justify-between gap-3 rounded-lg px-3 py-2 text-sm ${inProgress || !isBlocking ? "bg-surface text-muted" : "bg-danger-soft text-danger"}`, children: [_jsxs("span", { className: "flex items-center gap-2", children: [inProgress || !isBlocking ? (_jsx(Info, { className: "size-4 shrink-0", "aria-hidden": "true" })) : (_jsx(AlertTriangle, { className: "size-4 shrink-0", "aria-hidden": "true" })), blocker.message] }), blocker.resolveUrl && !inProgress && (_jsxs(Button, { variant: "secondary", onPress: () => window.open(blocker.resolveUrl, "_blank", "noopener,noreferrer"), children: [actionLabel(blocker), _jsx(ExternalLink, { className: "size-3.5" })] }))] }));
+}
+function ReadyRow({ className }) {
+    return (_jsx("p", { className: `text-sm text-muted ${className ?? ""}`, children: "This workspace is cleared to use every part of the service." }));
+}
+/**
+ * Renders `children` only once the workspace clears every blocking gate.
+ *
+ * The hard version of `ConnectReadinessBanner`, for a route that genuinely
+ * cannot function while blocked. Prefer the banner where the page still does
+ * something useful - a gate that hides a whole screen behind a verification
+ * notice is a worse experience than one that lets people look around while
+ * they sort it out.
+ *
+ * **This is a UX gate, not a security boundary.** The readiness read reaches
+ * your own origin and a determined browser can ignore whatever it says. The
+ * authoritative check is `client.entitlements.getReadiness` on your server,
+ * before you do the thing.
+ */
+export function ConnectReadinessGate({ children, fallback, loading, className, }) {
+    const { session, isLoading: sessionLoading } = useConnect();
+    const { data, isLoading } = useConnectEntitlements();
+    if (sessionLoading || (session?.user && isLoading)) {
+        return _jsx(_Fragment, { children: loading ?? _jsx(ConnectReadinessBanner, { className: className }) });
+    }
+    if (!session?.user)
+        return _jsx(_Fragment, { children: fallback ?? null });
+    if (data && isReady(data.readiness))
+        return _jsx(_Fragment, { children: children });
+    return (_jsx(_Fragment, { children: fallback ?? (_jsx(Card, { className: className, children: _jsx(Card.Content, { className: "py-6", children: _jsx(ConnectReadinessBanner, {}) }) })) }));
+}
+/**
+ * `ready` as the server computed it, with a local fallback.
+ *
+ * The server's own `ready` flag is authoritative and used when present; the
+ * blocker scan behind it exists so an older Connect that omits the field
+ * cannot be read as "ready" by default. Failing open on an absent gate is the
+ * wrong direction for a field that means "may this workspace be here at all".
+ */
+function isReady(readiness) {
+    return typeof readiness.ready === "boolean"
+        ? readiness.ready
+        : blockingBlockers(readiness).length === 0;
+}

package/dist/esm/client/components/subscribe-dialog.js

@@ -0,0 +1,57 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { Button, Modal } from "@heroui/react";
+import { ArrowRight, ExternalLink, Info } from "lucide-react";
+import { formatPrice, monthlyOf } from "./plan-pricing.js";
+/** GST is quoted exclusive everywhere in Connect; this is the same arithmetic `calculateGST` does server-side. */
+function withGst(price, gstRate) {
+    return price + Math.round(price * (gstRate / 100));
+}
+function cadenceOf(plan) {
+    return plan.billingInterval === "annual" ? "year" : "month";
+}
+const HEADING = {
+    subscribe: "Confirm subscription",
+    upgrade: "Confirm upgrade",
+    downgrade: "Confirm downgrade",
+    // A change of cadence is neither, and must not borrow either word - moving
+    // to annual billing costs less per month but more today, so calling it a
+    // downgrade misdescribes both the product and the bill. See `PlanAction`.
+    "switch-to-annual": "Switch to annual billing",
+    "switch-to-monthly": "Switch to monthly billing",
+    current: "Current plan",
+};
+/**
+ * The review step before a customer is sent to Connect.
+ *
+ * It exists because the hand-off is a context switch, and a context switch
+ * the customer did not expect reads as being dumped somewhere. So this says
+ * what they are about to buy, what it costs with GST, what happens to the
+ * cycle they are part-way through, and - plainly - that the payment itself
+ * happens on Connect. Then one button, which opens it.
+ *
+ * **Every number here is a preview, and deliberately never the last word.**
+ * The authoritative price is computed by Connect against the real cart:
+ * proration is priced against the actual cycle, a coupon is validated
+ * against the plan it is being applied to, trial eligibility depends on
+ * whether this organization has ever subscribed to this service before, and
+ * an accumulated credit is deducted. None of that is knowable from the
+ * partner's origin, so this component states the list price and says where
+ * the final figure comes from rather than quietly guessing at one.
+ */
+export function ConnectSubscribeDialog({ plan, action, current, coupon, onClose, onConfirm, }) {
+    const currentPlan = current?.plan ?? null;
+    const isIntervalSwitch = action === "switch-to-annual" || action === "switch-to-monthly";
+    // Every action except a first subscribe is a move *from* something, so all
+    // of them get the from -> to comparison. A cadence switch is the newest
+    // member and the one most in need of it: the two prices differ by an order
+    // of magnitude, and showing only the new one reads as a price rise.
+    const isChange = action === "upgrade" || action === "downgrade" || isIntervalSwitch;
+    return (_jsx(Modal.Backdrop, { isOpen: plan !== null, onOpenChange: (open) => !open && onClose(), children: _jsx(Modal.Container, { size: "sm", children: _jsxs(Modal.Dialog, { children: [_jsx(Modal.CloseTrigger, { onPress: onClose }), _jsx(Modal.Header, { children: _jsx(Modal.Heading, { children: HEADING[action] }) }), plan && (_jsxs(_Fragment, { children: [_jsxs(Modal.Body, { className: "flex flex-col gap-4", children: [isChange && currentPlan ? (_jsxs("div", { className: "flex items-center gap-3 text-sm", children: [_jsxs("div", { className: "min-w-0", children: [_jsx("p", { className: "truncate text-muted", children: currentPlan.name }), _jsxs("p", { className: "text-xs text-muted", children: [formatPrice(currentPlan.price), "/", currentPlan.billingInterval === "annual" ? "yr" : "mo"] })] }), _jsx(ArrowRight, { className: "size-4 shrink-0 text-muted", "aria-hidden": "true" }), _jsxs("div", { className: "min-w-0", children: [_jsx("p", { className: "truncate font-medium text-foreground", children: plan.name }), _jsxs("p", { className: "text-xs text-muted", children: [formatPrice(plan.price), "/", plan.billingInterval === "annual" ? "yr" : "mo"] })] })] })) : (_jsxs("div", { children: [_jsx("p", { className: "font-medium text-foreground", children: plan.name }), plan.description && _jsx("p", { className: "text-xs text-muted", children: plan.description })] })), _jsxs("div", { className: "flex flex-col gap-1 border-t border-separator pt-3 text-sm", children: [_jsxs("div", { className: "flex justify-between text-muted", children: [_jsx("span", { children: plan.name }), _jsx("span", { children: formatPrice(plan.price) })] }), _jsxs("div", { className: "flex justify-between text-muted", children: [_jsxs("span", { children: ["GST (", plan.gstRate, "%)"] }), _jsx("span", { children: formatPrice(withGst(plan.price, plan.gstRate) - plan.price) })] }), _jsxs("div", { className: "flex justify-between border-t border-separator pt-1 font-semibold text-foreground", children: [_jsxs("span", { children: ["Per ", cadenceOf(plan)] }), _jsx("span", { children: formatPrice(withGst(plan.price, plan.gstRate)) })] }), plan.billingInterval === "annual" && (_jsxs("p", { className: "text-xs text-muted", children: ["Works out to ", formatPrice(monthlyOf(withGst(plan.price, plan.gstRate), "annual")), " a month, billed yearly."] }))] }), plan.trialDays ? (_jsxs("p", { className: "text-xs text-accent", children: [plan.trialDays, "-day free trial, if this workspace has not subscribed to this service before."] })) : null, coupon?.trim() ? (_jsxs("p", { className: "text-xs text-muted", children: ["Coupon ", _jsx("span", { className: "font-mono text-foreground", children: coupon.trim() }), " is carried over and validated on Connect."] })) : null, _jsxs("div", { className: "flex gap-2 rounded-lg bg-surface p-3 text-xs text-muted", children: [_jsx(Info, { className: "mt-0.5 size-4 shrink-0", "aria-hidden": "true" }), _jsxs("div", { className: "flex flex-col gap-1", children: [action === "subscribe" && (_jsx("p", { children: "Payment is completed on Connect, where your card or UPI mandate is set up and the tax invoice is issued. This page updates by itself once it is done." })), action === "upgrade" && (_jsxs("p", { children: ["Connect prices the difference for the days left in your current cycle and collects just that amount now. From the next cycle you are billed the ", plan.name, " rate."] })), action === "downgrade" && (_jsx("p", { children: "You keep what you have paid for. Connect works out the unused part of this cycle and applies it as credit or a refund, depending on how this service is configured." })), isIntervalSwitch && (
+                                                    // Not a proration. The cycle you are on ends, so this is
+                                                    // the one action where the amount collected can exceed a
+                                                    // single cycle's list price - or be nothing at all, with
+                                                    // the balance carried as credit. Saying so here is the
+                                                    // difference between an expected bill and a surprise.
+                                                    _jsxs("p", { children: ["Your billing cycle restarts on confirmation. Connect values the days left on", " ", currentPlan?.name ?? "your current plan", ", takes that off a full", " ", plan.billingInterval === "annual" ? "year" : "month", " at the ", plan.name, " rate, and collects the difference. Anything left over is carried as credit against your next invoices rather than refunded."] })), _jsx("p", { children: "Nothing is charged from this page - it has no access to your payment details." })] })] })] }), _jsxs(Modal.Footer, { children: [_jsx(Button, { variant: "secondary", onPress: onClose, children: "Cancel" }), _jsxs(Button, { variant: "primary", onPress: onConfirm, children: ["Continue on Connect", _jsx(ExternalLink, { className: "size-3.5" })] })] })] }))] }) }) }));
+}

package/dist/esm/client/components/subscription.js

@@ -0,0 +1,181 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { Button, Card, Chip, Skeleton } from "@heroui/react";
+import { AlertTriangle, ArrowRight, Clock, CreditCard, ExternalLink, Users } from "lucide-react";
+import { useConnect, useConnectEntitlements } from "../provider.js";
+import { formatPrice } from "./plan-pricing.js";
+import { ConnectLinkButton } from "./link-button.js";
+/** Where the plan catalogue lives in the host app. Overridable, because not every app mounts it at `/plans`. */
+const DEFAULT_PLANS_HREF = "/plans";
+function formatDate(iso) {
+    return new Date(iso).toLocaleDateString(undefined, { day: "numeric", month: "short", year: "numeric" });
+}
+export function resolveSubscriptionState(subscription, isTrialing) {
+    const detail = subscription?.subscription;
+    if (!detail)
+        return "none";
+    if (detail.status === "paused" || detail.status === "cancelled")
+        return "problem";
+    if (detail.status === "created" || detail.status === "authenticated")
+        return "pending";
+    if (detail.cancelAtPeriodEnd)
+        return "cancelling";
+    return isTrialing ? "trialing" : "active";
+}
+/**
+ * `isTrialing` lives on the *session* block, not on `SubscriptionDetail`.
+ *
+ * A small wart of the wire format worth centralising rather than rediscovering:
+ * `/entitlements` describes the subscription in full but cannot tell trialing
+ * from paying, and `/session` carries the one boolean that can. Both come from
+ * the same provider, so reading across them here costs nothing.
+ */
+function useSubscriptionState() {
+    const { session } = useConnect();
+    const { data, isLoading } = useConnectEntitlements();
+    const subscription = data?.subscription ?? null;
+    return {
+        isLoading,
+        subscription,
+        detail: subscription?.subscription ?? null,
+        plan: subscription?.plan ?? null,
+        state: resolveSubscriptionState(subscription, session?.subscription?.isTrialing ?? false),
+    };
+}
+/**
+ * The "you are not on a plan yet" card.
+ *
+ * Points at your **own** `/plans` page rather than opening Connect, and that is
+ * the deliberate part: choosing a plan is browsing, it belongs in your product
+ * where your pricing story is, and only the final confirmation needs to happen
+ * on Connect. Sending someone straight out of the app to pick is a context
+ * switch two steps too early.
+ *
+ * Rendered on its own it is just a card; `ConnectSubscriptionGate` is the usual
+ * way in, since it picks this only when there is genuinely nothing to show.
+ */
+export function ConnectNoSubscriptionCard({ plansHref = DEFAULT_PLANS_HREF, title = "You're not on a plan yet", description = "Pick a plan to unlock the full service. You can change or cancel it whenever you like.", className, }) {
+    return (_jsxs(Card, { className: className, children: [_jsxs(Card.Header, { children: [_jsx(Card.Title, { children: title }), _jsx(Card.Description, { children: description })] }), _jsx(Card.Footer, { children: _jsxs(ConnectLinkButton, { href: plansHref, variant: "primary", children: ["See plans", _jsx(ArrowRight, { className: "size-3.5" })] }) })] }));
+}
+/**
+ * The current subscription at a glance: plan, what it costs, what happens next,
+ * and one way into Connect to change it.
+ *
+ * The counterpart to `ConnectNoSubscriptionCard` - the same slot in the
+ * signed-up state - so an account or settings page can render this and get the
+ * right thing either way.
+ *
+ * Dates are formatted, never computed. "Renews on 3 Mar" is a fact from the
+ * wire; "renews in 12 days" would be a clock read during render, which is
+ * impure and re-renders wrong.
+ */
+export function ConnectSubscriptionCard({ plansHref, className }) {
+    const { appUrl } = useConnect();
+    const { isLoading, detail, plan, state } = useSubscriptionState();
+    if (isLoading)
+        return _jsx(Skeleton, { className: `h-48 rounded-xl ${className ?? ""}` });
+    if (!detail || !plan)
+        return _jsx(ConnectNoSubscriptionCard, { plansHref: plansHref, className: className });
+    return (_jsxs(Card, { className: className, children: [_jsxs(Card.Header, { children: [_jsxs("div", { className: "flex items-start justify-between gap-2", children: [_jsx(Card.Title, { children: plan.name }), _jsx(SubscriptionChip, { state: state })] }), _jsxs(Card.Description, { children: [formatPrice(plan.price), " + ", plan.gstRate, "% GST per", " ", plan.billingInterval === "annual" ? "year" : "month"] })] }), _jsxs(Card.Content, { className: "flex flex-col gap-2 text-sm", children: [_jsx(NextEvent, { detail: detail, state: state }), _jsx(ConnectSeatUsage, { plan: plan, detail: detail })] }), _jsxs(Card.Footer, { className: "flex flex-wrap gap-2", children: [_jsxs(Button, { variant: "secondary", onPress: () => window.open(`${appUrl}/billing/subscriptions/${detail.id}`, "_blank", "noopener,noreferrer"), children: ["Manage on Connect", _jsx(ExternalLink, { className: "size-3.5" })] }), _jsx(ConnectLinkButton, { href: plansHref ?? DEFAULT_PLANS_HREF, variant: "tertiary", children: "Change plan" })] })] }));
+}
+function SubscriptionChip({ state }) {
+    switch (state) {
+        case "trialing":
+            return _jsx(Chip, { className: "bg-accent-soft text-accent", children: "Free trial" });
+        case "cancelling":
+            return _jsx(Chip, { className: "bg-surface text-muted", children: "Ending soon" });
+        case "pending":
+            return _jsx(Chip, { className: "bg-surface text-muted", children: "Confirming payment" });
+        case "problem":
+            return _jsx(Chip, { className: "bg-danger-soft text-danger", children: "Needs attention" });
+        default:
+            return _jsx(Chip, { className: "bg-accent-soft text-accent", children: "Active" });
+    }
+}
+/** The one sentence that matters most: what happens next, and when. */
+function NextEvent({ detail, state, }) {
+    const endsOn = detail.currentBillingCycle?.endDate;
+    if (state === "cancelling") {
+        return (_jsxs("span", { className: "flex items-center gap-2 text-muted", children: [_jsx(Clock, { className: "size-4 shrink-0", "aria-hidden": "true" }), endsOn ? `Access ends on ${formatDate(endsOn)}.` : "Access ends at the end of this cycle."] }));
+    }
+    if (state === "pending") {
+        return (_jsxs("span", { className: "flex items-center gap-2 text-muted", children: [_jsx(CreditCard, { className: "size-4 shrink-0", "aria-hidden": "true" }), "Waiting for your first payment to confirm."] }));
+    }
+    if (state === "problem") {
+        return (_jsxs("span", { className: "flex items-center gap-2 text-danger", children: [_jsx(AlertTriangle, { className: "size-4 shrink-0", "aria-hidden": "true" }), "This subscription isn't active. Settle it on Connect to restore access."] }));
+    }
+    if (!detail.nextBillingDate)
+        return null;
+    return (_jsxs("span", { className: "flex items-center gap-2 text-muted", children: [_jsx(Clock, { className: "size-4 shrink-0", "aria-hidden": "true" }), state === "trialing"
+                ? `Your first charge is on ${formatDate(detail.nextBillingDate)}.`
+                : `Renews on ${formatDate(detail.nextBillingDate)}.`] }));
+}
+/**
+ * Seats used against what the plan includes.
+ *
+ * Only meaningful for `"fixed"` and `"per-seat"` - `"unlimited"` has nothing to
+ * count against, so it renders nothing rather than a meter that is always
+ * empty. Under `"per-seat"` going over is billable rather than blocked, so it
+ * says what the extra costs instead of warning.
+ */
+export function ConnectSeatUsage({ plan, detail, className, }) {
+    if (plan.seats.model === "unlimited")
+        return null;
+    const included = plan.seats.included ?? 0;
+    const over = detail.seatCount - included;
+    return (_jsxs("span", { className: `flex items-center gap-2 text-muted ${className ?? ""}`, children: [_jsx(Users, { className: "size-4 shrink-0", "aria-hidden": "true" }), detail.seatCount, " of ", included, " seat", included === 1 ? "" : "s", " used", over > 0 &&
+                (plan.seats.model === "per-seat"
+                    ? ` - ${over} extra at ${formatPrice(plan.seats.pricePerExtraSeat ?? 0)} each`
+                    : ` - ${over} over the plan's limit`)] }));
+}
+/**
+ * A trial that is running, and when it converts.
+ *
+ * Renders only while trialing, so it can live permanently in a layout. It says
+ * the charge date rather than a countdown for the same reason
+ * `ConnectSubscriptionCard` does - a countdown means reading the clock while
+ * rendering.
+ *
+ * The wire carries `isTrialing` but no trial *end* date; `nextBillingDate` on a
+ * trialing subscription is the first charge, which is the date a customer
+ * actually cares about anyway.
+ */
+export function ConnectTrialBanner({ plansHref, className }) {
+    const { appUrl } = useConnect();
+    const { detail, state } = useSubscriptionState();
+    if (state !== "trialing" || !detail)
+        return null;
+    return (_jsxs("div", { className: `flex flex-wrap items-center justify-between gap-3 rounded-lg bg-accent-soft px-3 py-2 text-sm text-accent ${className ?? ""}`, children: [_jsxs("span", { className: "flex items-center gap-2", children: [_jsx(Clock, { className: "size-4 shrink-0", "aria-hidden": "true" }), "You're on a free trial", detail.nextBillingDate ? `. Your first charge is on ${formatDate(detail.nextBillingDate)}.` : "."] }), _jsxs("div", { className: "flex items-center gap-2", children: [_jsx(ConnectLinkButton, { href: plansHref ?? DEFAULT_PLANS_HREF, variant: "tertiary", children: "Compare plans" }), _jsxs(Button, { variant: "secondary", onPress: () => window.open(`${appUrl}/billing/subscriptions/${detail.id}`, "_blank", "noopener,noreferrer"), children: ["Manage", _jsx(ExternalLink, { className: "size-3.5" })] })] })] }));
+}
+/**
+ * Renders `children` for a subscribed workspace, and the "pick a plan" card for
+ * everyone else.
+ *
+ * **Never renders the fallback while loading.** That flash - "you're not
+ * subscribed" for 200ms, then the real content - is the specific bug this
+ * component exists to make impossible, and it is what hand-rolled versions of
+ * it get wrong: the honest states are "still asking" and "asked, and the answer
+ * is no", and only the second one is a sales pitch.
+ *
+ * **This is a UX gate, not a security boundary** - same caveat as
+ * `ConnectReadinessGate`. Anything that must not happen without a subscription
+ * is checked on your server with `client.entitlements.hasFeature`.
+ */
+export function ConnectSubscriptionGate({ children, plansHref, fallback, loading, allowTrialing = true, allowPending = true, className, }) {
+    const { session, isLoading: sessionLoading } = useConnect();
+    const { isLoading, state } = useSubscriptionState();
+    if (sessionLoading || (session?.user && isLoading)) {
+        return _jsx(_Fragment, { children: loading ?? _jsx(Skeleton, { className: `h-48 rounded-xl ${className ?? ""}` }) });
+    }
+    if (!session?.user)
+        return _jsx(_Fragment, { children: fallback ?? null });
+    const allowed = state === "active" ||
+        (allowTrialing && state === "trialing") ||
+        (allowPending && state === "pending") ||
+        // Cancelling still means paid-for access until the cycle ends. Locking
+        // someone out the moment they press cancel takes away what they bought.
+        state === "cancelling";
+    if (allowed)
+        return _jsx(_Fragment, { children: children });
+    return _jsx(_Fragment, { children: fallback ?? _jsx(ConnectNoSubscriptionCard, { plansHref: plansHref, className: className }) });
+}