@cosmoops/connect-sdk 0.1.0

package/dist/esm/client/components/usage-meter.js

@@ -0,0 +1,65 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Card, Skeleton } from "@heroui/react";
+import { AlertTriangle } from "lucide-react";
+import { useConnect, useConnectAddonUsage } from "../provider.js";
+import { formatPrice } from "./plan-pricing.js";
+function formatUnits(value, unit) {
+    return `${value.toLocaleString("en-IN")} ${unit}`;
+}
+function formatDate(iso) {
+    return new Date(iso).toLocaleDateString(undefined, { day: "numeric", month: "short" });
+}
+/**
+ * How much of each consumable add-on this workspace has left.
+ *
+ * Reads the balance Connect actually debits, so the number here and the number
+ * `consumeAddon` enforces cannot disagree. Before the `addons:read` endpoint
+ * existed this component was impossible to write honestly: a service could
+ * spend an allowance down on every request and the only thing the API exposed
+ * was the list of add-on *ids* on the subscription.
+ *
+ * **It shows `balance` against `includedPerCycle`, and never a "used" figure.**
+ * With `carryForward` an unspent balance survives the cycle boundary, so
+ * `included - balance` can go negative - a meter that runs backwards. Real
+ * consumption for a cycle is a ledger question, and computing it from a
+ * balance would be a guess rendered as a fact.
+ */
+export function ConnectUsageMeter({ addonIds, hideWhenEmpty = true, title = "Usage this cycle", className, }) {
+    const { session } = useConnect();
+    const { data, isLoading, error } = useConnectAddonUsage();
+    if (!session?.user)
+        return null;
+    if (isLoading)
+        return _jsx(Skeleton, { className: `h-40 rounded-xl ${className ?? ""}` });
+    if (error || !data)
+        return null;
+    // Defended here as well as in `billing.getAddonUsage`, and deliberately so:
+    // `data` is whatever the host app's bridge returned, which a partner can
+    // route, wrap or proxy. This component's contract is that it renders nothing
+    // when there is nothing to meter, and it should hold for a malformed body as
+    // much as for an empty list.
+    const available = data.addons ?? [];
+    const addons = addonIds
+        ? addonIds
+            .map((id) => available.find((addon) => addon.addonId === id))
+            .filter((addon) => !!addon)
+        : available;
+    if (addons.length === 0) {
+        if (hideWhenEmpty)
+            return null;
+        return (_jsx(Card, { className: className, children: _jsxs(Card.Header, { children: [_jsx(Card.Title, { children: title }), _jsx(Card.Description, { children: "No metered add-ons on this plan." })] }) }));
+    }
+    return (_jsxs(Card, { className: className, children: [_jsxs(Card.Header, { children: [_jsx(Card.Title, { children: title }), data.resetsAt && _jsxs(Card.Description, { children: ["Resets on ", formatDate(data.resetsAt), "."] })] }), _jsx(Card.Content, { className: "flex flex-col gap-4", children: addons.map((addon) => (_jsx(AddonRow, { addon: addon }, addon.addonId))) })] }));
+}
+function AddonRow({ addon }) {
+    const overdrawn = addon.balance < 0;
+    // Carried-forward balance can exceed the grant, so the bar is clamped at
+    // both ends rather than assuming `0 <= balance <= includedPerCycle`. An
+    // unclamped width renders as a bar overflowing its own track.
+    const fraction = addon.includedPerCycle > 0 ? Math.min(1, Math.max(0, addon.balance / addon.includedPerCycle)) : 0;
+    const carried = addon.balance > addon.includedPerCycle ? addon.balance - addon.includedPerCycle : 0;
+    return (_jsxs("div", { className: "flex flex-col gap-1.5", children: [_jsxs("div", { className: "flex flex-wrap items-baseline justify-between gap-2 text-sm", children: [_jsx("span", { className: "font-medium text-foreground", children: addon.name }), _jsxs("span", { className: overdrawn ? "text-danger" : "text-muted", children: [overdrawn
+                                ? `${formatUnits(Math.abs(addon.balance), addon.unit)} over`
+                                : `${formatUnits(addon.balance, addon.unit)} left`, _jsxs("span", { className: "text-muted", children: [" of ", formatUnits(addon.includedPerCycle, addon.unit)] })] })] }), _jsx("div", { className: "h-1.5 w-full overflow-hidden rounded-full bg-surface", role: "meter", "aria-label": `${addon.name} remaining`, "aria-valuenow": addon.balance, "aria-valuemin": 0, "aria-valuemax": addon.includedPerCycle, children: _jsx("div", { className: `h-full rounded-full ${overdrawn ? "bg-danger" : "bg-accent"}`, style: { width: `${overdrawn ? 100 : fraction * 100}%` } }) }), carried > 0 && (_jsxs("p", { className: "text-xs text-muted", children: ["Includes ", formatUnits(carried, addon.unit), " carried over from last cycle."] })), overdrawn && addon.overagePricePerUnit !== null && (_jsxs("p", { className: "flex items-center gap-1.5 text-xs text-danger", children: [_jsx(AlertTriangle, { className: "size-3.5 shrink-0", "aria-hidden": "true" }), "Billed at ", formatPrice(addon.overagePricePerUnit), " per ", addon.unit, " beyond your allowance."] })), !overdrawn && addon.overagePolicy === "reject" && addon.balance === 0 && (_jsxs("p", { className: "flex items-center gap-1.5 text-xs text-danger", children: [_jsx(AlertTriangle, { className: "size-3.5 shrink-0", "aria-hidden": "true" }), "Nothing left this cycle - further use is blocked until it resets."] }))] }));
+}

package/dist/esm/client/components/user-menu.js

@@ -0,0 +1,164 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Avatar, Button, Chip, Modal, Separator, Skeleton, ToggleButton, ToggleButtonGroup, } from "@heroui/react";
+import { CreditCard, ExternalLink, Laptop, LogOut, Moon, ReceiptText, Sun, UserRound, } from "lucide-react";
+import { useConnect } from "../provider.js";
+import { ConnectMark } from "../mark.js";
+import { ConnectAccountSessions } from "./account-sessions.js";
+const THEME_OPTIONS = [
+    { value: "light", label: "Light", icon: Sun },
+    { value: "dark", label: "Dark", icon: Moon },
+    { value: "system", label: "System", icon: Laptop },
+];
+function initials(name, email) {
+    const source = name?.trim() || email?.trim() || "";
+    const parts = source.split(/[\s@._-]+/).filter(Boolean);
+    return (parts.slice(0, 2).map((part) => part[0]).join("") || "?").toUpperCase();
+}
+function openExternal(url) {
+    window.open(url, "_blank", "noopener,noreferrer");
+}
+/** `dispatch_admin` / `billing-viewer` -> `Dispatch admin`. */
+function humanizeRole(role) {
+    const words = role.replace(/[_-]+/g, " ").trim();
+    return words.charAt(0).toUpperCase() + words.slice(1);
+}
+/**
+ * The subscription chip, and only when there is something to say.
+ *
+ * A plain "Active" badge is noise - it restates the default. A trial that is
+ * running out, a subscription paused mid-dunning, or one already cancelled
+ * are the three states where the account modal is exactly where a user goes
+ * looking, and the chip is what points them at Billing.
+ */
+function subscriptionChip(subscription) {
+    if (!subscription)
+        return null;
+    if (subscription.isTrialing) {
+        return (_jsx(Chip, { size: "sm", variant: "soft", color: "warning", children: "Trial" }));
+    }
+    if (subscription.status === "paused") {
+        return (_jsx(Chip, { size: "sm", variant: "soft", color: "warning", children: "Paused" }));
+    }
+    if (subscription.status === "cancelled") {
+        return (_jsx(Chip, { size: "sm", variant: "soft", color: "danger", children: "Cancelled" }));
+    }
+    return null;
+}
+/**
+ * One of the three Connect destinations, as a tile rather than a menu row.
+ *
+ * These are not sibling actions of "Sign out" and should not queue up in the
+ * same vertical list as it - they are three places to *go*, all at another
+ * origin, and a row of equal-weight tiles says that at a glance where four
+ * stacked text buttons said "pick one of four unrelated things". The
+ * external-link mark stays on every one of them: they open in a new tab, and
+ * that is a promise the affordance has to make before the click, not after.
+ *
+ * `w-full` is load-bearing, not decoration: HeroUI's `.button` base is
+ * `w-fit`, so a tile dropped into a grid cell shrinks to its own label and
+ * the three of them come out ragged and unequal.
+ */
+function DestinationTile({ icon, label, url, }) {
+    return (_jsxs(Button, { variant: "tertiary", "aria-label": `${label} (opens in a new tab)`, className: "relative h-auto w-full flex-col items-center justify-center gap-2 rounded-xl border border-border bg-surface px-2 py-4 hover:bg-surface-secondary", onPress: () => openExternal(url), children: [_jsx(ExternalLink, { className: "absolute end-2 top-2 size-3 text-muted", "aria-hidden": "true" }), _jsx("span", { className: "flex size-9 items-center justify-center rounded-full bg-surface-secondary text-muted", children: icon }), _jsx("span", { className: "text-xs font-medium text-foreground", children: label })] }));
+}
+/**
+ * Avatar and name in the trigger; an identity card, the three Connect
+ * destinations (Profile, Billing, Connect), an optional appearance control,
+ * this account's active sessions, and sign-out in the modal it opens.
+ *
+ * Profile/Billing/Connect open in a **new tab**, each marked with an
+ * external-link icon. They are a different application at a different
+ * origin, and navigating the host app away to reach them would lose
+ * whatever the user was doing here. Sign out is the only action that acts
+ * in place, which is why it sits alone in the footer rather than as a fourth
+ * item in the same list as three navigations.
+ *
+ * The session list is account-wide, not scoped to this service - see
+ * `ConnectUserSession`'s doc comment in `types.ts`. Appearance only renders
+ * when both `theme` and `onThemeChange` are supplied.
+ *
+ * Renders nothing when signed out - pair it with `<ConnectLoginButton>`, which
+ * renders nothing when signed *in*, and the two swap cleanly with no branch in
+ * your own layout.
+ *
+ * On the HeroUI shape: the trigger is a plain `<Button>` as a **direct child**
+ * of `<Modal>`, not wrapped in `<Modal.Trigger>`. `Dropdown.Trigger` (and by
+ * the same construction, `Modal.Trigger`) is itself a React Aria `Button`, so
+ * wrapping one produces a button inside a button - invalid markup, and press
+ * handling stops working. Kept uncontrolled (no `isOpen`/`onOpenChange`),
+ * matching `<ConnectAppsGrid>`'s own `<Modal>` - nothing here needs to close
+ * the modal programmatically; sign-out uses `slot="close"` instead.
+ */
+export function ConnectUserMenu({ compact = false, onSignOut, className, theme, onThemeChange, }) {
+    const { session, isLoading, signOut, appUrl } = useConnect();
+    if (isLoading) {
+        return (_jsxs("div", { className: `flex items-center gap-2 ${className ?? ""}`, children: [_jsx(Skeleton, { className: "size-8 shrink-0 rounded-full" }), !compact && _jsx(Skeleton, { className: "h-4 w-24" })] }));
+    }
+    const user = session?.user;
+    if (!user)
+        return null;
+    const label = user.displayName ?? user.email ?? "Account";
+    const role = session?.serviceRole?.role;
+    const planChip = subscriptionChip(session?.subscription ?? null);
+    return (_jsxs(Modal, { children: [_jsxs(Button, { variant: "tertiary", "aria-label": `Account: ${label}`, className: `gap-1 pl-1 ${className ?? ""}`, children: [_jsx(Avatar, { size: "sm", color: "accent", variant: "soft", children: _jsx(Avatar.Fallback, { children: initials(user.displayName, user.email) }) }), !compact && _jsx("span", { className: "text-sm font-medium text-foreground", children: label })] }), _jsx(Modal.Backdrop, { children: _jsx(Modal.Container, { size: "md", scroll: "inside", children: _jsxs(Modal.Dialog, { children: [_jsx(Modal.CloseTrigger, {}), _jsx(Modal.Header, { children: _jsx(Modal.Heading, { children: "Account" }) }), _jsxs(Modal.Body, { className: "flex flex-col gap-5", children: [_jsxs("div", { className: "flex items-start gap-3 rounded-xl border border-border bg-surface-secondary p-4", children: [_jsx(Avatar, { size: "lg", color: "accent", variant: "soft", children: _jsx(Avatar.Fallback, { children: initials(user.displayName, user.email) }) }), _jsxs("div", { className: "min-w-0 flex-1", children: [_jsx("p", { className: "truncate text-sm font-semibold text-foreground", children: label }), user.email && _jsx("p", { className: "truncate text-xs text-muted", children: user.email }), _jsxs("div", { className: "mt-2 flex flex-wrap items-center gap-1.5", children: [_jsx(Chip, { size: "sm", variant: "soft", children: user.organizationName }), role && (_jsx(Chip, { size: "sm", variant: "soft", color: "accent", children: humanizeRole(role) })), planChip, !user.emailVerified && (_jsx(Chip, { size: "sm", variant: "soft", color: "warning", children: "Email unverified" }))] })] })] }), _jsxs("div", { className: "grid grid-cols-3 gap-2", children: [_jsx(DestinationTile, { icon: _jsx(UserRound, { className: "size-4", "aria-hidden": "true" }), label: "Profile", url: `${appUrl}/profile` }), _jsx(DestinationTile, { icon: _jsx(CreditCard, { className: "size-4", "aria-hidden": "true" }), label: "Billing", url: `${appUrl}/billing` }), _jsx(DestinationTile, { icon: _jsx(ConnectMark, { className: "size-4" }), label: "Connect", url: appUrl })] }), theme && onThemeChange && (_jsxs("div", { className: "flex flex-col gap-2", children: [_jsx("p", { className: "text-sm font-medium text-foreground", children: "Appearance" }), _jsx(ToggleButtonGroup, { fullWidth: true, "aria-label": "Theme", selectionMode: "single", disallowEmptySelection: true, selectedKeys: [theme], onSelectionChange: (keys) => {
+                                                    const [next] = [...keys];
+                                                    if (typeof next === "string")
+                                                        onThemeChange(next);
+                                                }, children: THEME_OPTIONS.map(({ value, label: optionLabel, icon: Icon }, index) => (_jsxs(ToggleButton, { id: value, children: [index > 0 && _jsx(ToggleButtonGroup.Separator, {}), _jsx(Icon, { className: "size-4", "aria-hidden": "true" }), optionLabel] }, value))) })] })), _jsx(Separator, {}), _jsx(ConnectAccountSessions, {})] }), _jsx(Modal.Footer, { children: _jsxs(Button, { slot: "close", fullWidth: true, variant: "tertiary", className: "text-danger", onPress: () => {
+                                        void signOut().then(onSignOut);
+                                    }, children: [_jsx(LogOut, { className: "size-4 shrink-0" }), "Sign out"] }) })] }) }) })] }));
+}
+/**
+ * The "Manage subscription" action on its own, for layouts that want it
+ * visible rather than buried in the account menu - a billing banner, an empty
+ * state, a settings page.
+ */
+export function ConnectManageSubscriptionButton({ className }) {
+    const { appUrl } = useConnect();
+    return (_jsxs(Button, { variant: "secondary", className: className, onPress: () => openExternal(`${appUrl}/billing`), children: [_jsx(CreditCard, { className: "size-4 shrink-0" }), "Manage subscription", _jsx(ExternalLink, { className: "size-3.5 shrink-0 text-muted" })] }));
+}
+/**
+ * Invoices and payment history, on Connect.
+ *
+ * A deep link rather than a component that lists them, and that is not a
+ * placeholder: nothing in `/api/v1/service/*` exposes invoices, so an SDK-side
+ * list would have nothing to read. It is also the right answer regardless -
+ * a GST tax invoice is a legal document with a fixed format, downloadable and
+ * emailed from one place, and a partner-rendered copy of one would be a second
+ * version of a record that must have exactly one.
+ */
+export function ConnectInvoicesButton({ className }) {
+    const { session, appUrl } = useConnect();
+    if (!session?.user)
+        return null;
+    return (_jsxs(Button, { variant: "tertiary", className: className, onPress: () => openExternal(`${appUrl}/billing/invoices`), children: [_jsx(ReceiptText, { className: "size-4 shrink-0" }), "Invoices", _jsx(ExternalLink, { className: "size-3.5 shrink-0 text-muted" })] }));
+}
+/**
+ * The "Profile" action on its own - the third of the three Connect
+ * destinations, alongside `ConnectManageSubscriptionButton` (Billing) and
+ * `ConnectHomeButton`.
+ *
+ * It was reachable only from inside `ConnectUserMenu`, which meant an app that
+ * builds its own account menu had to hardcode `${appUrl}/profile` to offer it.
+ */
+export function ConnectProfileButton({ className }) {
+    const { session, appUrl } = useConnect();
+    if (!session?.user)
+        return null;
+    return (_jsxs(Button, { variant: "tertiary", className: className, onPress: () => openExternal(`${appUrl}/profile`), children: [_jsx(UserRound, { className: "size-4 shrink-0" }), "Profile", _jsx(ExternalLink, { className: "size-3.5 shrink-0 text-muted" })] }));
+}
+/** A plain "Open Connect" button, for a footer or a help menu. */
+export function ConnectHomeButton({ className }) {
+    const { appUrl } = useConnect();
+    return (_jsxs(Button, { variant: "tertiary", className: className, onPress: () => openExternal(appUrl), children: [_jsx(ConnectMark, { className: "size-4 shrink-0" }), "Connect", _jsx(ExternalLink, { className: "size-3.5 shrink-0 text-muted" })] }));
+}
+/** Sign out on its own, for a settings page that wants it as a destructive row. */
+export function ConnectSignOutButton({ onSignOut, className, }) {
+    const { session, signOut } = useConnect();
+    if (!session?.user)
+        return null;
+    return (_jsxs(Button, { variant: "tertiary", className: className, onPress: () => {
+            void signOut().then(onSignOut);
+        }, children: [_jsx(LogOut, { className: "size-4 shrink-0" }), "Sign out"] }));
+}

package/dist/esm/client/index.js

@@ -0,0 +1,47 @@
+"use client";
+/**
+ * Browser half of `@cosmoops/connect-sdk` - React components and hooks.
+ *
+ * Holds no credential. Everything here talks to your own origin, where
+ * `createConnectHandler` from `@cosmoops/connect-sdk/server` holds the API key
+ * and reaches Connect.
+ *
+ * Styling is HeroUI v3 semantic tokens only (`accent`, `muted`, `surface`,
+ * `separator`, ...), never a hardcoded colour - so these components inherit
+ * whatever theme the host service platform already configured, and one theme
+ * change lands identically in all of them.
+ */
+export { ConnectProvider, useConnect, useConnectUser, useConnectEntitlements, useConnectPlans, useConnectApps, useConnectAddonUsage, useConnectSessions, useConnectResource, CONNECT_APP_URL, } from "./provider.js";
+// Re-exported from the root entry rather than kept there alone: it is a pure
+// helper, but every caller is UI code, and making a component file reach two
+// entry points for one function is friction with nothing behind it.
+export { blockingBlockers, normalizePlanFeatures } from "../helpers.js";
+export { ConnectError, isConnectError } from "../errors.js";
+export { ConnectMark } from "./mark.js";
+export { ConnectLogo } from "./components/logo.js";
+export { ConnectLoginButton, ConnectRegisterButton } from "./components/auth-buttons.js";
+export { ConnectUserMenu, ConnectManageSubscriptionButton, ConnectInvoicesButton, ConnectProfileButton, ConnectHomeButton, ConnectSignOutButton, } from "./components/user-menu.js";
+// Built, compiled into `dist/`, and reachable from no entry point until now -
+// `ConnectUserMenu` was the only thing that could render it.
+export { ConnectAccountSessions } from "./components/account-sessions.js";
+export { ConnectAppsGrid } from "./components/apps-grid.js";
+export { ConnectPlans } from "./components/plans.js";
+export { ConnectSubscribeDialog } from "./components/subscribe-dialog.js";
+// The subscribe / upgrade / downgrade flow's two moving parts, exported so a
+// partner can drive the same hand-off from its own pricing page instead of
+// `<ConnectPlans>` - the pricing table is one presentation of the flow, not
+// the flow itself.
+// Subscription state, gates and the surfaces around the plan grid.
+export { ConnectSubscriptionGate, ConnectNoSubscriptionCard, ConnectSubscriptionCard, ConnectTrialBanner, ConnectSeatUsage, resolveSubscriptionState, } from "./components/subscription.js";
+export { ConnectReadinessBanner, ConnectReadinessGate } from "./components/readiness.js";
+export { ConnectFeatureGate, useConnectFeature } from "./components/feature-gate.js";
+export { ConnectUsageMeter } from "./components/usage-meter.js";
+export { ConnectPlansPage } from "./components/plans-page.js";
+export { useConnectCheckout, buildCheckoutUrl } from "./use-checkout.js";
+export { formatPrice, monthlyOf, resolveAction, annualSaving, discountLabel, ACTION_LABEL, 
+// The tier model, exported because a partner writing its own pricing grid
+// needs the same pairing `ConnectPlans` uses. Grouping a flat plan list by
+// hand means matching on `name`, which Connect neither enforces unique nor
+// keeps stable across a rename - `planGroup` is the field that exists to
+// answer this, and `groupPlansByTier` is how to read it.
+groupPlansByTier, resolvePlanGroup, } from "./components/plan-pricing.js";

package/dist/esm/client/mark.js

@@ -0,0 +1,13 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * The Connect mark - concentric rings on a solid accent badge.
+ *
+ * Painted from `--accent` / `--accent-foreground`, the same HeroUI tokens the
+ * host app themes, so the badge tracks whatever palette a service platform has
+ * configured rather than carrying a hardcoded CosmoOps green into someone
+ * else's brand.
+ */
+export function ConnectMark({ className = "size-5" }) {
+    return (_jsxs("svg", { viewBox: "0 0 32 32", xmlns: "http://www.w3.org/2000/svg", "aria-hidden": "true", className: className, children: [_jsx("rect", { width: "32", height: "32", rx: "9", fill: "var(--accent)" }), _jsxs("g", { stroke: "var(--accent-foreground)", strokeWidth: "2", fill: "none", strokeLinecap: "round", strokeLinejoin: "round", children: [_jsx("circle", { cx: "16", cy: "16", r: "2.5" }), _jsx("circle", { cx: "16", cy: "16", r: "6" }), _jsx("circle", { cx: "16", cy: "16", r: "9.5" })] })] }));
+}

package/dist/esm/client/provider.js

@@ -0,0 +1,247 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { createContext, useCallback, useContext, useEffect, useMemo, useRef, useState } from "react";
+export const CONNECT_APP_URL = "https://connect.cosmoops.com";
+const ConnectContext = createContext(null);
+/**
+ * Wraps the part of your app that shows Connect UI.
+ *
+ * Holds one session read, shared by every component below it, so a page with a
+ * user menu, an apps grid and a plan table makes one request rather than three.
+ * There is no API key here and there cannot be: everything goes to your own
+ * origin, where `createConnectHandler` holds the credential.
+ *
+ * ```tsx
+ * // Next.js - clientId comes from NEXT_PUBLIC_CONNECT_CLIENT_ID
+ * <ConnectProvider>
+ *   <App />
+ * </ConnectProvider>
+ * ```
+ */
+export function ConnectProvider({ clientId = process.env.NEXT_PUBLIC_CONNECT_CLIENT_ID ?? "", basePath = "/api/connect", redirectUri, appUrl = CONNECT_APP_URL, fetch: fetchImpl, children, }) {
+    // One state cell, not three. `isLoading` is *derived* from "no result yet"
+    // rather than set - a `setIsLoading(true)` at the top of an effect is a
+    // synchronous setState inside that effect, which cascades an extra render
+    // and is what `react-hooks/set-state-in-effect` flags. Everything below
+    // writes state only from an async callback.
+    const [result, setResult] = useState(null);
+    const isLoading = result === null;
+    const session = result?.session ?? null;
+    const error = result?.error ?? null;
+    // One entry per path. Held in a ref, not state, because a cache write must
+    // not re-render every consumer of this context - only the component awaiting
+    // that promise cares.
+    const cache = useRef(new Map());
+    const fetchResource = useCallback((path) => {
+        const key = `${basePath}${path}`;
+        const existing = cache.current.get(key);
+        if (existing)
+            return existing;
+        const pending = (fetchImpl ?? globalThis.fetch)(key, {
+            credentials: "same-origin",
+            headers: { accept: "application/json" },
+        })
+            .then(async (response) => {
+            const body = await response.json().catch(() => null);
+            if (!response.ok) {
+                throw new Error(body?.error?.message ?? `Connect bridge returned ${response.status}`);
+            }
+            return body;
+        })
+            .catch((cause) => {
+            // A failed read must not be cached, or the UI can never recover
+            // without a reload.
+            cache.current.delete(key);
+            throw cause;
+        });
+        cache.current.set(key, pending);
+        return pending;
+    }, [basePath, fetchImpl]);
+    const mutateResource = useCallback(async (path, body) => {
+        const response = await (fetchImpl ?? globalThis.fetch)(`${basePath}${path}`, {
+            method: "POST",
+            credentials: "same-origin",
+            headers: {
+                accept: "application/json",
+                ...(body !== undefined ? { "content-type": "application/json" } : {}),
+            },
+            body: body !== undefined ? JSON.stringify(body) : undefined,
+        });
+        const responseBody = await response.json().catch(() => null);
+        if (!response.ok) {
+            throw new Error(responseBody?.error?.message ?? `Connect bridge returned ${response.status}`);
+        }
+        // Only this path's own entry - see this method's doc comment for why
+        // a blunt full-cache clear (like `refresh()`/`signOut()` use) is wrong
+        // here.
+        cache.current.delete(`${basePath}${path}`);
+        return responseBody;
+    }, [basePath, fetchImpl]);
+    const invalidateResource = useCallback((path) => {
+        cache.current.delete(`${basePath}${path}`);
+    }, [basePath]);
+    const refresh = useCallback(async () => {
+        cache.current.clear();
+        try {
+            const session = await fetchResource("/session");
+            setResult({ session, error: null });
+        }
+        catch (cause) {
+            // A bridge that cannot be reached is reported as signed out *with* an
+            // error, so a Login button still renders rather than the UI hanging on
+            // skeletons forever.
+            setResult({
+                session: { user: null, subscription: null, serviceRole: null },
+                error: cause instanceof Error ? cause.message : "Could not reach Connect",
+            });
+        }
+    }, [fetchResource]);
+    useEffect(() => {
+        // A documented false positive: `refresh` writes state only after awaiting
+        // the bridge, so nothing here is synchronous - but the rule cannot follow
+        // an await boundary across a `useCallback` and reports the reachable
+        // `setResult`. Fetching on mount is the sanctioned pattern; the rule
+        // targets the synchronous case, which this is not.
+        // eslint-disable-next-line react-hooks/set-state-in-effect
+        void refresh();
+    }, [refresh]);
+    const signIn = useCallback((options = {}) => {
+        const url = new URL("/sso/authorize", appUrl);
+        url.searchParams.set("client_id", clientId);
+        url.searchParams.set("response_type", "code");
+        url.searchParams.set("scope", "openid");
+        if (redirectUri)
+            url.searchParams.set("redirect_uri", redirectUri);
+        if (options.prompt)
+            url.searchParams.set("prompt", options.prompt);
+        // `state` is deliberately absent: it must be generated and stored
+        // server-side to be worth anything, so the redirect goes through your own
+        // start route, which mints one and forwards. See `ConnectLoginButton`.
+        window.location.href = redirectUri ? url.toString() : `${basePath}/signin${options.prompt ? "?prompt=create" : ""}`;
+    }, [appUrl, basePath, clientId, redirectUri]);
+    const signOut = useCallback(async () => {
+        await (fetchImpl ?? globalThis.fetch)(`${basePath}/logout`, {
+            method: "POST",
+            credentials: "same-origin",
+        }).catch(() => { });
+        cache.current.clear();
+        setResult({ session: { user: null, subscription: null, serviceRole: null }, error: null });
+    }, [basePath, fetchImpl]);
+    const value = useMemo(() => ({
+        clientId,
+        appUrl,
+        session,
+        isLoading,
+        error,
+        signIn,
+        signOut,
+        refresh,
+        fetchResource,
+        mutateResource,
+        invalidateResource,
+    }), [
+        clientId,
+        appUrl,
+        session,
+        isLoading,
+        error,
+        signIn,
+        signOut,
+        refresh,
+        fetchResource,
+        mutateResource,
+        invalidateResource,
+    ]);
+    return _jsx(ConnectContext.Provider, { value: value, children: children });
+}
+export function useConnect() {
+    const value = useContext(ConnectContext);
+    if (!value) {
+        throw new Error("useConnect must be used inside <ConnectProvider>. Wrap your app once, near the root.");
+    }
+    return value;
+}
+/** The signed-in user, or `null`. Sugar over `useConnect().session`. */
+export function useConnectUser() {
+    return useConnect().session?.user ?? null;
+}
+/** Readiness gates and the live subscription, fetched on first use. */
+export function useConnectEntitlements() {
+    return useConnectResource("/entitlements");
+}
+/**
+ * What is left of every consumable add-on on this workspace's subscription.
+ *
+ * The read half of `client.billing.consumeAddon` - a service that meters its
+ * own end users had no way to show them what remained until this existed.
+ * Empty `addons` means there is nothing to meter, which is not an error.
+ */
+export function useConnectAddonUsage() {
+    return useConnectResource("/addons");
+}
+/** This service's plan catalog. */
+export function useConnectPlans() {
+    return useConnectResource("/plans");
+}
+/** The apps this organization can open. */
+export function useConnectApps() {
+    return useConnectResource("/apps");
+}
+/**
+ * This Connect account's own login sessions - account-wide, not scoped to
+ * this service, see `SessionsListResponse`'s doc comment. The component
+ * that calls this is also the one that must own any revoke actions and call
+ * the returned `refetch()` afterward - see `mutateResource`'s doc comment
+ * for why nothing does that automatically.
+ */
+export function useConnectSessions() {
+    return useConnectResource("/sessions");
+}
+/**
+ * One bridge read, shared through the provider's cache.
+ *
+ * Only fetches once a user is known: every resource route needs a session, so
+ * firing before one exists just buys a guaranteed 401.
+ */
+export function useConnectResource(path) {
+    const { fetchResource, session, isLoading: sessionLoading } = useConnect();
+    // Stamped with the `path` it belongs to, so switching paths reports loading
+    // without a synchronous `setIsLoading(true)` - and, more usefully, so a
+    // resolved response for a previous path can never be read as this one's.
+    const [entry, setEntry] = useState(null);
+    const [version, setVersion] = useState(0);
+    useEffect(() => {
+        // Signed out is handled by derivation below rather than by writing state
+        // here - a synchronous setState inside an effect costs an extra render pass
+        // and is what `react-hooks/set-state-in-effect` exists to catch.
+        if (sessionLoading || !session?.user)
+            return;
+        let active = true;
+        fetchResource(path)
+            .then((data) => {
+            if (active)
+                setEntry({ path, data, error: null });
+        })
+            .catch((cause) => {
+            if (active) {
+                setEntry({ path, data: null, error: cause instanceof Error ? cause.message : "Request failed" });
+            }
+        });
+        return () => {
+            active = false;
+        };
+        // `version` is otherwise unread - it exists purely to force this effect
+        // to re-run on `refetch()`, after the caller has already evicted this
+        // path's cache entry via `mutateResource`.
+    }, [fetchResource, path, session?.user, sessionLoading, version]);
+    const signedOut = !sessionLoading && !session?.user;
+    const loaded = entry?.path === path ? entry : null;
+    return {
+        data: loaded?.data ?? null,
+        // Signed out is a settled answer, not a pending one - a gated component
+        // should render its signed-out state, not skeletons forever.
+        isLoading: !signedOut && !loaded,
+        error: loaded?.error ?? null,
+        refetch: () => setVersion((v) => v + 1),
+    };
+}