@cosmoops/connect-sdk 0.3.0 → 0.6.0

package/dist/cjs/server/webhooks.js

@@ -0,0 +1,127 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.verifyConnectWebhook = verifyConnectWebhook;
+exports.createConnectWebhookHandler = createConnectWebhookHandler;
+const node_crypto_1 = require("node:crypto");
+/**
+ * How far out of date a timestamp may be. Five minutes, the same value
+ * Connect signs against and the same one Stripe uses - so a backend that
+ * already verifies Stripe webhooks needs no new assumptions.
+ */
+const TIMESTAMP_TOLERANCE_SECONDS = 300;
+const SIGNATURE_HEADER = "connect-signature";
+/**
+ * Verifies a `Connect-Signature` header against the raw request body.
+ *
+ * Exported on its own for anyone wiring this into a framework
+ * `createConnectWebhookHandler` does not cover. The **raw** body matters:
+ * verify before parsing, and never re-serialise - `JSON.stringify(await
+ * req.json())` produces a different string whenever key order or number
+ * formatting differs, and the signature will not match.
+ *
+ * Returns a boolean and never explains which check failed. Reporting "bad
+ * timestamp" separately from "bad signature" tells whoever is probing which
+ * half of a forgery to keep working on.
+ */
+function verifyConnectWebhook(rawBody, signatureHeader, secret, now = new Date()) {
+    if (!signatureHeader)
+        return false;
+    const parts = new Map(signatureHeader
+        .split(",")
+        .map((part) => part.trim().split("="))
+        .filter((pair) => pair.length === 2)
+        .map(([key, value]) => [key, value]));
+    const timestamp = Number(parts.get("t"));
+    const presented = parts.get("v1");
+    if (!presented || !Number.isFinite(timestamp))
+        return false;
+    // Absolute difference: a timestamp from the future is as much a sign of a
+    // forgery as a stale one, and accepting it would let somebody mint a
+    // signature that stays valid indefinitely.
+    const nowSeconds = Math.floor(now.getTime() / 1000);
+    if (Math.abs(nowSeconds - timestamp) > TIMESTAMP_TOLERANCE_SECONDS)
+        return false;
+    const expected = (0, node_crypto_1.createHmac)("sha256", secret)
+        .update(`${timestamp}.${rawBody}`)
+        .digest("hex");
+    // `timingSafeEqual` throws on a length mismatch, and a wrong-length hex
+    // string is exactly what a probe looks like - so lengths are compared
+    // first and only equal-length buffers reach it.
+    if (presented.length !== expected.length)
+        return false;
+    return (0, node_crypto_1.timingSafeEqual)(Buffer.from(presented, "utf8"), Buffer.from(expected, "utf8"));
+}
+/**
+ * A ready-made `POST` route for Connect's webhooks.
+ *
+ * ```ts
+ * export const POST = createConnectWebhookHandler({
+ *   secret: process.env.CONNECT_WEBHOOK_SECRET!,
+ *   on: {
+ *     "organization.deletion_scheduled": ({ organizationId, purgeAfter }) =>
+ *       freeze(organizationId, purgeAfter),
+ *     "organization.deletion_cancelled": ({ organizationId }) => unfreeze(organizationId),
+ *     "organization.deleted": ({ organizationId }) => purge(organizationId),
+ *   },
+ * })
+ * ```
+ *
+ * Three behaviours worth knowing, because each of them is a decision rather
+ * than an accident:
+ *
+ * **An unverified request gets a 401 and nothing else happens.** No parsing,
+ * no logging of the body, no handler. The endpoint is a public URL, so
+ * anything reachable before the signature check is reachable by anyone.
+ *
+ * **An unhandled event type is a 200.** Connect adds event types over time,
+ * and answering 4xx to one you have not written code for would dead-letter
+ * it immediately and, after enough of them, disable your endpoint. Silence
+ * is the correct answer to "we do not care about this one".
+ *
+ * **A throwing handler produces a 500, on purpose.** That is what makes
+ * Connect retry. Swallowing the error would acknowledge an event you failed
+ * to process, and the retry ladder is the only thing standing between a
+ * transient failure and a permanently missed deletion.
+ *
+ * Delivery is at-least-once and unordered. Dedupe on `envelope.id`, and
+ * reconcile against the readiness endpoint rather than trusting arrival
+ * order - the pull channel is authoritative, this one is fast.
+ */
+function createConnectWebhookHandler(options) {
+    return async function POST(request) {
+        // Read as text and verify before parsing. `JSON.stringify(await
+        // request.json())` is not the same string that was signed - key order and
+        // number formatting both differ - so a handler that parses first can
+        // never verify.
+        const rawBody = await request.text();
+        const signature = request.headers.get(SIGNATURE_HEADER);
+        if (!verifyConnectWebhook(rawBody, signature, options.secret)) {
+            return new Response("Invalid signature", { status: 401 });
+        }
+        let envelope;
+        try {
+            envelope = JSON.parse(rawBody);
+        }
+        catch {
+            // Signed by us and still unparseable is not something a retry fixes.
+            return new Response("Malformed payload", { status: 400 });
+        }
+        const handler = options.on[envelope.type];
+        if (!handler)
+            return new Response(null, { status: 200 });
+        try {
+            await handler(envelope.data, envelope);
+        }
+        catch (error) {
+            if (options.onError) {
+                await options.onError(error, envelope);
+            }
+            else {
+                console.error(`Connect webhook ${envelope.type} (${envelope.id}) failed:`, error);
+            }
+            // Deliberately a 500: it is what makes Connect retry. See the doc above.
+            return new Response("Handler failed", { status: 500 });
+        }
+        return new Response(null, { status: 200 });
+    };
+}

package/dist/esm/cli/doctor.js

@@ -159,8 +159,8 @@ function checkEnv(root) {
             status: "fail",
             title: `${name} set`,
             detail: declaredEmpty
-                ? `Declared but empty in .env.local. The value is in your service's Setup tab in Connect.`
-                : `Not found in .env.local or the environment. Both values are in your service's Setup tab in Connect.`,
+                ? `Declared but empty in .env.local. The value is in your service's Integration tab in Connect.`
+                : `Not found in .env.local or the environment. Both values are in your service's Integration tab in Connect.`,
         };
     });
 }
@@ -173,7 +173,7 @@ function checkRedirectUri() {
     return {
         status: "warn",
         title: "Redirect URI registered in Connect",
-        detail: "Not checkable from here. Confirm {your origin}/api/connect/callback is listed as a redirect URI in your service's Setup tab - including the deployed origin, not just http://localhost:3000.",
+        detail: "Not checkable from here. Confirm {your origin}/api/connect/callback is listed as a redirect URI in your service's Integration tab - including the deployed origin, not just http://localhost:3000.",
     };
 }
 const MARKER = { pass: "  ok  ", warn: " note ", fail: " FAIL " };

package/dist/esm/cli/init.js

@@ -39,7 +39,7 @@ const PLANS_PAGE = `"use client";
 // with the other exports) whenever you want your own copy or layout.
 export { ConnectPlansPage as default } from "@cosmoops/connect-sdk/client";
 `;
-const ENV_TEMPLATE = `# CosmoOps Connect - values come from your service's Setup tab.
+const ENV_TEMPLATE = `# CosmoOps Connect - values come from your service's Integration tab.
 CONNECT_API_KEY=
 CONNECT_CLIENT_ID=
 `;
@@ -106,7 +106,7 @@ export function runInit(argv = []) {
         console.log(`  ${marker}  ${relative(root, target)}  - ${scaffold.description}`);
     }
     const env = ensureEnv(root);
-    console.log(`  ${env === "skipped" ? "exists " : env === "appended" ? "updated" : "created"}  .env.local  - fill in the two values from your service's Setup tab`);
+    console.log(`  ${env === "skipped" ? "exists " : env === "appended" ? "updated" : "created"}  .env.local  - fill in the two values from your service's Integration tab`);
     // The two steps a scaffolder must not do for you: editing an existing layout
     // means parsing and rewriting JSX someone else wrote, and the redirect URI
     // lives in Connect, not in this repo.
@@ -132,7 +132,7 @@ Three things left, all one-time:
      Tailwind roots its content scan inside node_modules and skips your app.
 
   3. Register {your origin}/api/connect/callback as a redirect URI in your
-     service's Setup tab in Connect.
+     service's Integration tab in Connect.
 
 No next.config.ts changes needed - not even transpilePackages: dist/ is
 already ES2022 with "use client" hoisted, so Turbopack and webpack consume it

package/dist/esm/client/components/access-gate.js

@@ -0,0 +1,158 @@
+"use client";
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+import { useState } from "react";
+import { Ban, AlertTriangle, Clock, CreditCard, ExternalLink, X } from "lucide-react";
+import { Button, Card, Skeleton } from "@heroui/react";
+import { blockingBlockers } from "../../helpers.js";
+import { useConnect, useConnectEntitlements } from "../provider.js";
+import { ENTER, m, MotionProvider } from "./motion.js";
+import { ConnectReadinessBanner } from "./readiness.js";
+function formatDate(iso) {
+    return new Date(iso).toLocaleDateString(undefined, { day: "numeric", month: "short", year: "numeric" });
+}
+/**
+ * The single composed answer to "can this workspace use my app right now,
+ * and if not, which of the four things is it": choose a plan, wait on
+ * approval, resolve an overdue payment, or - a suspended workspace - none of
+ * the above, because nothing short of a platform admin fixes that one.
+ *
+ * Reuses the existing single sources of truth rather than re-deriving them:
+ * `blockingBlockers()` (`helpers.ts`) for severity, the same readiness read
+ * `ConnectReadinessGate`/`ConnectReadinessBanner` already use. `ConnectAccessGate`
+ * is a priority ordering over the same data, not a second opinion about it.
+ *
+ * Priority, first match wins: `suspended` > `no_subscription` >
+ * `onboarding_pending` > any other blocking code (`blocked`) >
+ * `payment_retry` (advisory - `children` still render) > `clear`.
+ */
+export function useConnectAccessGate() {
+    const { session, isLoading: sessionLoading } = useConnect();
+    const { data, isLoading: entitlementsLoading } = useConnectEntitlements();
+    if (sessionLoading || (session?.user && entitlementsLoading)) {
+        return { state: "loading", blocker: null, paymentRetry: null };
+    }
+    if (!session?.user) {
+        return { state: "signed_out", blocker: null, paymentRetry: null };
+    }
+    if (!data) {
+        // Signed in, not loading, yet nothing came back - a failed read (see
+        // `error` on `useConnectEntitlements`). Fail open rather than hard-block
+        // the whole app on a network hiccup; `ConnectReadinessBanner` makes the
+        // same call for its own "no data" branch.
+        return { state: "clear", blocker: null, paymentRetry: null };
+    }
+    const readiness = data.readiness;
+    const blocking = blockingBlockers(readiness);
+    const suspended = blocking.find((b) => b.code === "organization_suspended");
+    if (suspended)
+        return { state: "suspended", blocker: suspended, paymentRetry: null };
+    const noSubscription = blocking.find((b) => b.code === "subscription_missing");
+    if (noSubscription)
+        return { state: "no_subscription", blocker: noSubscription, paymentRetry: null };
+    const onboardingPending = blocking.find((b) => b.code === "onboarding_approval_pending");
+    if (onboardingPending) {
+        return { state: "onboarding_pending", blocker: onboardingPending, paymentRetry: null };
+    }
+    if (blocking.length > 0) {
+        return { state: "blocked", blocker: blocking[0] ?? null, paymentRetry: null };
+    }
+    const paymentRetry = readiness.readiness.blockers.find((b) => b.code === "payment_retry_pending");
+    if (paymentRetry)
+        return { state: "payment_retry", blocker: null, paymentRetry };
+    return { state: "clear", blocker: null, paymentRetry: null };
+}
+/**
+ * Wrap your app's content once - typically in your root layout, alongside
+ * (not instead of) your own header/nav - and it renders exactly one of: the
+ * hard-block card for a suspended workspace, one with no plan, or one
+ * waiting on approval; your `children` plus a dismissible payment-due banner
+ * during an automatic dunning retry; or just `children` once everything is
+ * clear.
+ *
+ * **Do not wrap your own plans/pricing page with this.** The `no_subscription`
+ * card's button sends someone to Connect's subscribe page directly (see
+ * `GateCard`'s doc comment on why - it used to link to your in-app `/plans`
+ * instead, which is a dead end once this gate hides that very page too), but
+ * a customer can still navigate to your plans page on their own (a nav link,
+ * a bookmark) and must actually see it there. Since the gate is mounted once
+ * around every route, carving out that exception is your router's job, not
+ * a prop on this component: check the current path in your layout/shell and
+ * skip wrapping `children` in `<ConnectAccessGate>` for that one route.
+ *
+ * **Signed-out renders `children`, not a fallback** - deliberately different
+ * from `ConnectReadinessGate`/`ConnectSubscriptionGate`, which show nothing
+ * until signed in. None of the four states this component composes is a
+ * property of a signed-out visitor, and a component mounted around your
+ * entire app must not hide a public landing page behind an empty gate. Your
+ * own sign-in flow decides what a signed-out visitor sees.
+ *
+ * **This is a UX gate, not a security boundary** - same caveat as every
+ * other gate in this package. The authoritative check is
+ * `client.entitlements.getReadiness` on your server, before you do the
+ * thing.
+ */
+export function ConnectAccessGate({ children, fallback, loading, className }) {
+    const gate = useConnectAccessGate();
+    if (gate.state === "loading") {
+        return _jsx(_Fragment, { children: loading ?? _jsx(Skeleton, { className: `h-32 rounded-xl ${className ?? ""}` }) });
+    }
+    if (gate.state === "signed_out" || gate.state === "clear") {
+        return _jsx(_Fragment, { children: children });
+    }
+    if (gate.state === "payment_retry") {
+        return (_jsxs(_Fragment, { children: [gate.paymentRetry && _jsx(PaymentRetryBanner, { blocker: gate.paymentRetry, className: className }), children] }));
+    }
+    return (_jsx(_Fragment, { children: fallback ?? _jsx(AccessGateFallback, { state: gate.state, blocker: gate.blocker, className: className }) }));
+}
+function AccessGateFallback({ state, blocker, className, }) {
+    if (state === "no_subscription") {
+        return (_jsx(GateCard, { icon: CreditCard, iconClassName: "text-accent", title: "Choose a plan to continue", message: blocker?.message ?? "This workspace isn't subscribed to this service yet.", actionLabel: "See plans", resolveUrl: blocker?.resolveUrl ?? null, className: className }));
+    }
+    if (state === "suspended") {
+        return (_jsx(GateCard, { icon: Ban, iconClassName: "text-danger", title: "Workspace suspended", message: blocker?.message ?? "This workspace has been suspended.", resolveUrl: null, className: className }));
+    }
+    if (state === "onboarding_pending") {
+        return (_jsx(GateCard, { icon: Clock, iconClassName: "text-muted", title: "Waiting on approval", message: blocker?.message ?? "This workspace is waiting on approval before it can use this service.", resolveUrl: null, className: className }));
+    }
+    // "blocked" - any other blocking code (verification, audience, seats, ...).
+    // Full fidelity for a code this component doesn't special-case: the same
+    // banner-in-a-card `ConnectReadinessGate` falls back to, rather than
+    // `GateCard`'s single-blocker shape - there can be more than one of these
+    // at once, and each already carries its own action.
+    return (_jsx(Card, { className: className, children: _jsx(Card.Content, { className: "py-6", children: _jsx(ConnectReadinessBanner, {}) }) }));
+}
+/**
+ * One card shape for every hard-block state: an icon, what's wrong, and -
+ * when the server sent a `resolveUrl` - the one button that fixes it,
+ * opening Connect directly in a new tab. The same pattern every other
+ * resolvable blocker in this package uses (`BlockerRow`, `PaymentRetryBanner`
+ * below) - `no_subscription` used to be the one exception, sending someone
+ * to the host app's own `/plans` page instead. That was a deliberate choice
+ * on `ConnectNoSubscriptionCard` (browsing plans belongs in your product),
+ * but inside a gate mounted around your *entire* app it is a dead end: the
+ * card replaces whatever page it is rendered on, including your own plans
+ * page if you did not carve it out (see `ConnectAccessGate`'s doc comment),
+ * so "see plans" landing back on the same blocked screen never gets anyone
+ * to a choice they can act on. Sending them to Connect's own subscribe page
+ * always resolves.
+ */
+function GateCard({ icon: Icon, iconClassName, title, message, actionLabel, resolveUrl, className, }) {
+    return (_jsx(MotionProvider, { children: _jsx(m.div, { initial: { opacity: 0, y: -6 }, animate: { opacity: 1, y: 0 }, transition: ENTER, children: _jsxs(Card, { className: className, children: [_jsxs(Card.Header, { children: [_jsxs("div", { className: "flex items-center gap-2", children: [_jsx(Icon, { className: `size-5 shrink-0 ${iconClassName}`, "aria-hidden": "true" }), _jsx(Card.Title, { children: title })] }), _jsx(Card.Description, { children: message })] }), resolveUrl && (_jsx(Card.Footer, { children: _jsxs(Button, { variant: "primary", onPress: () => window.open(resolveUrl, "_blank", "noopener,noreferrer"), children: [actionLabel ?? "Resolve on Connect", _jsx(ExternalLink, { className: "size-3.5" })] }) }))] }) }) }));
+}
+/**
+ * The skippable payment-due warning. Dismissal is scoped to this specific
+ * dunning cycle - keyed by `graceEndsAt`, so a dismissed banner reappears on
+ * its own if a *new* retry cycle starts (a different `graceEndsAt`) even
+ * though an old dismissal is still on record.
+ */
+function PaymentRetryBanner({ blocker, className, }) {
+    const dismissKey = blocker.graceEndsAt ? `connect_dismissed_payment_retry_pending_${blocker.graceEndsAt}` : null;
+    const [dismissed, setDismissed] = useState(() => dismissKey !== null && typeof window !== "undefined" && window.localStorage.getItem(dismissKey) === "1");
+    if (dismissed)
+        return null;
+    return (_jsx(MotionProvider, { children: _jsxs(m.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 ?? ""}`, role: "status", initial: { opacity: 0, y: -6 }, animate: { opacity: 1, y: 0 }, transition: ENTER, children: [_jsxs("span", { className: "flex items-center gap-2", children: [_jsx(AlertTriangle, { className: "size-4 shrink-0", "aria-hidden": "true" }), blocker.message, blocker.graceEndsAt && ` Resolve by ${formatDate(blocker.graceEndsAt)} to avoid losing access.`] }), _jsxs("div", { className: "flex items-center gap-2", children: [blocker.resolveUrl && (_jsxs(Button, { variant: "secondary", onPress: () => window.open(blocker.resolveUrl, "_blank", "noopener,noreferrer"), children: ["Resolve payment", _jsx(ExternalLink, { className: "size-3.5" })] })), _jsx(Button, { variant: "tertiary", isIconOnly: true, "aria-label": "Dismiss", onPress: () => {
+                                setDismissed(true);
+                                if (dismissKey && typeof window !== "undefined")
+                                    window.localStorage.setItem(dismissKey, "1");
+                            }, children: _jsx(X, { className: "size-4" }) })] })] }) }));
+}

package/dist/esm/client/components/account-sessions.js

@@ -4,6 +4,8 @@ import { useState } from "react";
 import { AlertDialog, Button, Chip, Skeleton } from "@heroui/react";
 import { LogOut, Monitor, MonitorSmartphone, Smartphone, Tablet } from "lucide-react";
 import { useConnect, useConnectSessions } from "../provider.js";
+import { AnimatePresence, EASE_OUT_QUART, m, MotionProvider } from "./motion.js";
+import { ICON, PANEL_FILL } from "./surfaces.js";
 import { formatRelativeTime } from "../../format-relative-time.js";
 const DEVICE_ICONS = {
     desktop: Monitor,
@@ -75,13 +77,13 @@ export function ConnectAccountSessions({ className, maxVisible = 4 }) {
     const [isRevokingOthers, setIsRevokingOthers] = useState(false);
     const [showAll, setShowAll] = useState(false);
     if (isLoading) {
-        return (_jsxs("section", { className: `flex flex-col gap-3 ${className ?? ""}`, children: [_jsx(Skeleton, { className: "h-4 w-28" }), _jsx("div", { className: "flex flex-col divide-y divide-border overflow-hidden rounded-xl border border-border bg-surface", children: Array.from({ length: 2 }, (_, index) => (_jsxs("div", { className: "flex items-center gap-3 px-3 py-3", children: [_jsx(Skeleton, { className: "size-9 shrink-0 rounded-lg" }), _jsxs("div", { className: "flex min-w-0 flex-1 flex-col gap-1.5", children: [_jsx(Skeleton, { className: "h-3.5 w-32" }), _jsx(Skeleton, { className: "h-3 w-24" })] })] }, index))) })] }));
+        return (_jsxs("section", { className: `flex flex-col gap-3 ${className ?? ""}`, children: [_jsx(Skeleton, { className: "h-4 w-28" }), _jsx("div", { className: `flex flex-col divide-y divide-border overflow-hidden rounded-xl border border-border ${PANEL_FILL}`, children: Array.from({ length: 2 }, (_, index) => (_jsxs("div", { className: "flex items-center gap-3 px-3 py-3", children: [_jsx(Skeleton, { className: "size-9 shrink-0 rounded-xl" }), _jsxs("div", { className: "flex min-w-0 flex-1 flex-col gap-1.5", children: [_jsx(Skeleton, { className: "h-3.5 w-32" }), _jsx(Skeleton, { className: "h-3 w-24" })] })] }, index))) })] }));
     }
     // A failed read used to render as *nothing*, which is indistinguishable
     // from "you have no other devices" - the one reading of this list that
     // should never be guessed at.
     if (error) {
-        return (_jsxs("section", { className: `flex flex-col gap-2 ${className ?? ""}`, children: [_jsx("p", { className: "text-sm font-medium text-foreground", children: "Active sessions" }), _jsx("p", { className: "rounded-xl border border-border bg-surface px-3 py-4 text-xs text-muted", children: "Could not load your sessions. Try again in a moment." })] }));
+        return (_jsxs("section", { className: `flex flex-col gap-2 ${className ?? ""}`, children: [_jsx("p", { className: "text-sm font-medium text-foreground", children: "Active sessions" }), _jsx("p", { className: `rounded-xl border border-border ${PANEL_FILL} px-3 py-4 text-xs text-muted`, children: "Could not load your sessions. Try again in a moment." })] }));
     }
     const sessions = ordered(data?.items ?? []);
     if (sessions.length === 0)
@@ -89,21 +91,21 @@ export function ConnectAccountSessions({ className, maxVisible = 4 }) {
     const hasOtherSessions = sessions.some((session) => !session.isCurrent);
     const isCollapsible = maxVisible > 0 && sessions.length > maxVisible;
     const visible = isCollapsible && !showAll ? sessions.slice(0, maxVisible) : sessions;
-    return (_jsxs("section", { className: `flex flex-col gap-3 ${className ?? ""}`, children: [_jsxs("div", { className: "flex items-start justify-between gap-3", children: [_jsxs("div", { className: "min-w-0", children: [_jsxs("p", { className: "flex items-center gap-2 text-sm font-medium text-foreground", children: ["Active sessions", _jsx(Chip, { size: "sm", variant: "soft", children: sessions.length })] }), _jsx("p", { className: "text-xs text-muted", children: "Devices signed in to your Connect account." })] }), hasOtherSessions && (_jsx(Button, { size: "sm", variant: "tertiary", className: "shrink-0 text-xs text-danger", isPending: isRevokingOthers, isDisabled: isRevokingOthers, onPress: () => {
-                            setIsRevokingOthers(true);
-                            void mutateResource("/sessions/revoke-others")
-                                .then(() => {
-                                invalidateResource("/sessions");
-                                refetch();
-                            })
-                                .finally(() => setIsRevokingOthers(false));
-                        }, children: "Sign out others" }))] }), _jsx("div", { className: "flex flex-col divide-y divide-border overflow-hidden rounded-xl border border-border bg-surface", children: visible.map((session) => {
-                    const Icon = DEVICE_ICONS[session.device.deviceType];
-                    return (_jsxs("div", { className: "flex items-center gap-3 px-3 py-2.5", children: [_jsx("span", { className: `flex size-9 shrink-0 items-center justify-center rounded-lg ${session.isCurrent ? "bg-accent-soft text-accent-soft-foreground" : "bg-surface-secondary text-muted"}`, children: _jsx(Icon, { className: "size-4", "aria-hidden": "true" }) }), _jsxs("div", { className: "min-w-0 flex-1", children: [_jsxs("span", { className: "flex items-center gap-2", children: [_jsx("span", { className: "truncate text-sm font-medium text-foreground", children: deviceLabel(session) }), session.isCurrent && (_jsx(Chip, { color: "accent", size: "sm", variant: "soft", className: "shrink-0", children: "This device" }))] }), _jsx("p", { className: "truncate text-xs text-muted", children: metaLine(session) })] }), !session.isCurrent && (_jsx(RevokeRow, { session: session, onRevoke: () => {
-                                    void mutateResource("/sessions/revoke", { sessionId: session.id }).then(() => {
-                                        invalidateResource("/sessions");
-                                        refetch();
-                                    });
-                                } }))] }, session.id));
-                }) }), isCollapsible && (_jsx(Button, { size: "sm", variant: "tertiary", className: "self-start text-xs", onPress: () => setShowAll((open) => !open), children: showAll ? "Show fewer" : `Show all ${sessions.length} devices` }))] }));
+    return (_jsx(MotionProvider, { children: _jsxs("section", { className: `flex flex-col gap-3 ${className ?? ""}`, children: [_jsxs("div", { className: "flex items-start justify-between gap-3", children: [_jsxs("div", { className: "min-w-0", children: [_jsxs("p", { className: "flex items-center gap-2 text-sm font-medium text-foreground", children: ["Active sessions", _jsx(Chip, { size: "sm", variant: "soft", children: sessions.length })] }), _jsx("p", { className: "text-xs text-muted", children: "Devices signed in to your Connect account." })] }), hasOtherSessions && (_jsx(Button, { size: "sm", variant: "tertiary", className: "shrink-0 text-xs text-danger", isPending: isRevokingOthers, isDisabled: isRevokingOthers, onPress: () => {
+                                setIsRevokingOthers(true);
+                                void mutateResource("/sessions/revoke-others")
+                                    .then(() => {
+                                    invalidateResource("/sessions");
+                                    refetch();
+                                })
+                                    .finally(() => setIsRevokingOthers(false));
+                            }, children: "Sign out others" }))] }), _jsx("div", { className: `flex flex-col divide-y divide-border overflow-hidden rounded-xl border border-border ${PANEL_FILL}`, children: _jsx(AnimatePresence, { initial: false, children: visible.map((session) => {
+                            const Icon = DEVICE_ICONS[session.device.deviceType];
+                            return (_jsxs(m.div, { layout: true, exit: { opacity: 0, height: 0, overflow: "hidden" }, transition: { duration: 0.25, ease: EASE_OUT_QUART }, className: "flex items-center gap-3 px-3 py-2.5", children: [_jsx("span", { className: `flex size-9 shrink-0 items-center justify-center rounded-xl ${session.isCurrent ? "bg-accent-soft text-accent-soft-foreground" : "bg-surface text-muted"}`, children: _jsx(Icon, { className: ICON, "aria-hidden": "true" }) }), _jsxs("div", { className: "min-w-0 flex-1", children: [_jsxs("span", { className: "flex items-center gap-2", children: [_jsx("span", { className: "truncate text-sm font-medium text-foreground", children: deviceLabel(session) }), session.isCurrent && (_jsx(Chip, { size: "sm", variant: "soft", color: "accent", className: "shrink-0", children: "This device" }))] }), _jsx("p", { className: "truncate text-xs text-muted", children: metaLine(session) })] }), !session.isCurrent && (_jsx(RevokeRow, { session: session, onRevoke: () => {
+                                            void mutateResource("/sessions/revoke", { sessionId: session.id }).then(() => {
+                                                invalidateResource("/sessions");
+                                                refetch();
+                                            });
+                                        } }))] }, session.id));
+                        }) }) }), isCollapsible && (_jsx(Button, { size: "sm", variant: "tertiary", className: "self-start text-xs", onPress: () => setShowAll((open) => !open), children: showAll ? "Show fewer" : `Show all ${sessions.length} devices` }))] }) }));
 }

package/dist/esm/client/components/app-shell.js

@@ -0,0 +1,154 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { useCallback, useState, useSyncExternalStore } from "react";
+import { Button, Drawer, Tooltip } from "@heroui/react";
+import { Menu, PanelLeftClose, PanelLeftOpen } from "lucide-react";
+import { useConnect } from "../provider.js";
+import { ConnectAccessGate } from "./access-gate.js";
+import { ConnectAppsGrid } from "./apps-grid.js";
+import { ConnectLoginButton, ConnectRegisterButton } from "./auth-buttons.js";
+import { ConnectLogo } from "./logo.js";
+import { ConnectSideNav, defaultRenderLink } from "./side-nav.js";
+import { ConnectUserMenu } from "./user-menu.js";
+import { gateExemptPaths, normalizePath, } from "./nav.js";
+import { useActivePath } from "../use-active-path.js";
+const COLLAPSED_KEY = "connect_sidenav_collapsed";
+const COLLAPSED_EVENT = "connect:sidenav-collapsed";
+/**
+ * The stored rail preference, or `null` when there isn't one (or when reading
+ * it is not allowed).
+ *
+ * `localStorage` throws outright in a partitioned iframe or with site data
+ * blocked, and an application frame is not worth losing over a preference.
+ */
+function collapsedSnapshot() {
+    try {
+        const stored = window.localStorage.getItem(COLLAPSED_KEY);
+        return stored === null ? null : stored === "1";
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * No preference on the server, which is the point: `useSyncExternalStore` uses
+ * this for the hydrating render and only then swaps in the real reading, so a
+ * returning user's collapsed rail can never make the server's HTML and the
+ * client's first pass disagree. Reading storage during render instead is a
+ * hydration mismatch waiting for its first user.
+ */
+function serverCollapsedSnapshot() {
+    return null;
+}
+function subscribeCollapsed(onStoreChange) {
+    // `storage` covers the app's other tabs; the custom event covers this one,
+    // which `storage` deliberately never fires in.
+    window.addEventListener("storage", onStoreChange);
+    window.addEventListener(COLLAPSED_EVENT, onStoreChange);
+    return () => {
+        window.removeEventListener("storage", onStoreChange);
+        window.removeEventListener(COLLAPSED_EVENT, onStoreChange);
+    };
+}
+/**
+ * The sidebar's brand row: the lockup when expanded, the badge alone when not.
+ */
+function BrandLink({ name, icon, homeHref, collapsed, renderLink, }) {
+    return renderLink({
+        href: homeHref,
+        className: `flex items-center rounded-lg focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-focus ${collapsed ? "justify-center" : ""}`,
+        // `ConnectLogo` names itself, but it does it with `role="img"` on a
+        // `<span>`, which the `<a>` wrapping it does not inherit as its own name.
+        "aria-label": `${name} home`,
+        children: _jsx(ConnectLogo, { name: name, icon: icon, collapsed: collapsed }),
+    });
+}
+/**
+ * The application frame every CosmoOps service platform runs inside: a
+ * collapsible sidebar, a top bar carrying the app launcher and the account
+ * menu, and your pages in the middle.
+ *
+ * This is the piece each partner was otherwise writing by hand, and writing
+ * slightly differently - which is how a family of services stops looking like
+ * one product. Everything that should be identical across platforms (the
+ * lockup, the rail geometry, the active-route treatment, the launcher, the
+ * account menu, the access gate) lives here; everything that genuinely
+ * differs is a prop:
+ *
+ * ```tsx
+ * "use client";
+ * import Link from "next/link";
+ * import { usePathname } from "next/navigation";
+ * import { ConnectAppShell } from "@cosmoops/connect-sdk/client";
+ * import { LayoutDashboard, Truck } from "lucide-react";
+ *
+ * export function Shell({ children }: { children: React.ReactNode }) {
+ *   return (
+ *     <ConnectAppShell
+ *       name="Dispatch"
+ *       icon={<Truck />}
+ *       activePath={usePathname()}
+ *       renderLink={(props) => <Link {...props} />}
+ *       nav={[
+ *         { label: "Overview", href: "/", icon: <LayoutDashboard className="size-5" /> },
+ *         { label: "Plans", href: "/plans", icon: <Truck className="size-5" />, gateExempt: true },
+ *       ]}
+ *     >
+ *       {children}
+ *     </ConnectAppShell>
+ *   );
+ * }
+ * ```
+ *
+ * There is no `isSignedIn` branch anywhere in here, and there should be none
+ * in yours: the auth buttons render nothing once a session exists, the user
+ * menu renders nothing without one, and the launcher renders nothing when
+ * signed out. The swap happens inside the components.
+ *
+ * It renders no provider of its own - mount `ConnectProvider` above it, once,
+ * so a page with a shell, a plan table and a usage meter still makes one
+ * session read.
+ */
+export function ConnectAppShell({ name, icon, homeHref = "/", nav, activePath, renderLink = defaultRenderLink, title, headerActions, sidebarFooter, footer, defaultCollapsed = false, collapsed: controlledCollapsed, onCollapsedChange, collapsible = true, showAppsGrid = true, showAuthButtons = true, theme, onThemeChange, gate = true, gateExemptRoutes, className, contentClassName, children, }) {
+    const { session, isLoading } = useConnect();
+    const pathname = useActivePath(activePath);
+    const [mobileOpen, setMobileOpen] = useState(false);
+    // The rail's own state lives in `localStorage`, read as an external store
+    // rather than copied into React state: it is shared with this app's other
+    // tabs, and the reading is not available during the render that hydrates.
+    const stored = useSyncExternalStore(subscribeCollapsed, collapsedSnapshot, serverCollapsedSnapshot);
+    const isControlled = controlledCollapsed !== undefined;
+    const collapsed = collapsible ? (isControlled ? controlledCollapsed : (stored ?? defaultCollapsed)) : false;
+    const toggleCollapsed = useCallback(() => {
+        const next = !collapsed;
+        onCollapsedChange?.(next);
+        if (isControlled)
+            return;
+        try {
+            window.localStorage.setItem(COLLAPSED_KEY, next ? "1" : "0");
+        }
+        catch {
+            // Not persisted - but the event below still moves the rail for this session.
+        }
+        window.dispatchEvent(new Event(COLLAPSED_EVENT));
+    }, [collapsed, isControlled, onCollapsedChange]);
+    const closeMobile = useCallback(() => setMobileOpen(false), []);
+    const currentPath = normalizePath(pathname);
+    const exempt = [...gateExemptPaths(nav), ...(gateExemptRoutes ?? []).map(normalizePath)];
+    const isExempt = exempt.some((path) => currentPath === path || currentPath.startsWith(`${path}/`));
+    // A signed-out visitor has no readiness to check and nothing to be blocked
+    // by; `ConnectAccessGate` passes them straight through, but mounting it at
+    // all costs an entitlements read that cannot succeed.
+    const signedOut = !isLoading && !session?.user;
+    const gated = gate && !isExempt && !signedOut;
+    const sideNav = (mobile) => (_jsx(ConnectSideNav, { nav: nav, activePath: pathname, renderLink: renderLink, collapsed: mobile ? false : collapsed, onNavigate: mobile ? closeMobile : undefined }));
+    return (_jsxs("div", { className: `flex h-screen bg-background ${className ?? ""}`, children: [_jsxs("aside", { "aria-label": "Sidebar", className: `hidden shrink-0 flex-col border-r border-border bg-surface transition-[width] duration-200 ease-in-out will-change-[width] md:flex ${collapsed ? "w-16" : "w-64"}`, children: [_jsx("div", { className: `flex h-16 shrink-0 items-center border-b border-border ${collapsed ? "justify-center px-2" : "px-4"}`, children: _jsx(BrandLink, { name: name, icon: icon, homeHref: homeHref, collapsed: collapsed, renderLink: renderLink }) }), _jsx("div", { className: `flex-1 overflow-y-auto py-4 ${collapsed ? "px-2" : "px-3"}`, children: sideNav(false) }), _jsxs("div", { className: `shrink-0 border-t border-border ${collapsed ? "flex flex-col items-center gap-2 p-2" : "flex flex-col gap-2 p-3"}`, children: [!collapsed && sidebarFooter, collapsible && (
+                            // The button goes in as a *direct* child, the way `Modal` and
+                            // `Dropdown` take theirs. `Tooltip.Trigger` renders a wrapper
+                            // `<div>` and puts the props it is given on that div - so an
+                            // `aria-label` passed there names a div nobody can reach and
+                            // leaves this icon-only button with no accessible name at all.
+                            // The wrapper is for trigger elements React Aria cannot drive
+                            // directly; a HeroUI `Button` is not one.
+                            _jsxs(Tooltip, { delay: 200, children: [_jsx(Button, { isIconOnly: true, variant: "tertiary", size: "sm", "aria-label": collapsed ? "Expand sidebar" : "Collapse sidebar", className: collapsed ? "" : "self-start", onPress: toggleCollapsed, children: collapsed ? _jsx(PanelLeftOpen, { className: "size-4" }) : _jsx(PanelLeftClose, { className: "size-4" }) }), _jsx(Tooltip.Content, { placement: "right", children: collapsed ? "Expand sidebar" : "Collapse sidebar" })] }))] })] }), _jsx(Drawer.Backdrop, { isOpen: mobileOpen, onOpenChange: setMobileOpen, children: _jsx(Drawer.Content, { placement: "left", className: "w-72 max-w-[80vw]", children: _jsxs(Drawer.Dialog, { "aria-label": "Navigation menu", children: [_jsx(Drawer.CloseTrigger, {}), _jsx(Drawer.Header, { children: _jsx(Drawer.Heading, { "aria-label": name, children: _jsx(ConnectLogo, { name: name, icon: icon }) }) }), _jsx(Drawer.Body, { children: sideNav(true) }), sidebarFooter && _jsx(Drawer.Footer, { className: "flex flex-col items-stretch gap-3", children: sidebarFooter })] }) }) }), _jsxs("div", { className: "flex min-w-0 flex-1 flex-col", children: [_jsxs("header", { className: "flex h-16 shrink-0 items-center gap-3 border-b border-border bg-surface px-4 md:px-6", children: [_jsx(Button, { isIconOnly: true, variant: "tertiary", size: "sm", className: "md:hidden", "aria-label": "Open navigation menu", onPress: () => setMobileOpen(true), children: _jsx(Menu, { className: "size-5" }) }), typeof title === "string" ? (_jsx("h1", { className: "truncate text-lg font-semibold text-foreground", children: title })) : (title), _jsxs("div", { className: "ml-auto flex items-center gap-1", children: [headerActions, showAppsGrid && _jsx(ConnectAppsGrid, {}), _jsx(ConnectUserMenu, { compact: true, theme: theme, onThemeChange: onThemeChange }), showAuthButtons && (_jsxs(_Fragment, { children: [_jsx(ConnectLoginButton, { size: "sm" }), _jsx(ConnectRegisterButton, { size: "sm" })] }))] })] }), _jsx("main", { className: "flex-1 overflow-y-auto", children: _jsxs("div", { className: contentClassName ?? "mx-auto w-full max-w-6xl px-4 py-6 md:px-6 md:py-8", children: [gated ? _jsx(ConnectAccessGate, { children: children }) : children, footer] }) })] })] }));
+}

package/dist/esm/client/components/apps-grid.js

@@ -3,6 +3,7 @@ import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-run
 import { Button, Modal, Skeleton } from "@heroui/react";
 import { AlertCircle, ExternalLink, LayoutGrid } from "lucide-react";
 import { useConnectApps, useConnect } from "../provider.js";
+import { ENTER, m, MotionProvider } from "./motion.js";
 function AppTile({ app }) {
     const disabled = app.launchUrl === null;
     const body = (_jsxs(_Fragment, { children: [_jsxs("span", { className: "relative flex size-12 items-center justify-center overflow-hidden rounded-xl bg-surface-secondary", children: [app.iconUrl ? (
@@ -35,7 +36,7 @@ export function ConnectAppsGrid({ className, label = "Switch app" }) {
     if (sessionLoading || !session?.user)
         return null;
     const apps = data?.apps ?? [];
-    return (_jsxs(Modal, { children: [_jsx(Button, { isIconOnly: true, variant: "primary", "aria-label": label, className: className, children: _jsx(LayoutGrid, { className: "size-5" }) }), _jsx(Modal.Backdrop, { children: _jsx(Modal.Container, { children: _jsxs(Modal.Dialog, { className: "sm:max-w-md", children: [_jsx(Modal.CloseTrigger, {}), _jsx(Modal.Header, { children: _jsx(Modal.Heading, { children: "Your apps" }) }), _jsxs(Modal.Body, { children: [isLoading && (_jsx("div", { className: "grid grid-cols-3 gap-2", children: Array.from({ length: 6 }, (_, index) => (_jsxs("div", { className: "flex flex-col items-center gap-2 p-3", children: [_jsx(Skeleton, { className: "size-12 rounded-xl" }), _jsx(Skeleton, { className: "h-3 w-14" })] }, index))) })), !isLoading && error && (_jsx("p", { className: "py-6 text-center text-sm text-danger", children: "Could not load your apps." })), !isLoading && !error && apps.length === 0 && (_jsx("p", { className: "py-6 text-center text-sm text-muted", children: "No other apps yet. Anything this workspace subscribes to shows up here." })), !isLoading && !error && apps.length > 0 && (_jsx("div", { className: "grid grid-cols-3 gap-2", children: apps.map((app) => (_jsx(AppTile, { app: app }, app.serviceId))) }))] }), _jsx(Modal.Footer, { children: _jsx(ConnectBrowseAllLink, {}) })] }) }) })] }));
+    return (_jsx(MotionProvider, { children: _jsxs(Modal, { children: [_jsx(Button, { isIconOnly: true, variant: "primary", "aria-label": label, className: className, children: _jsx(LayoutGrid, { className: "size-5" }) }), _jsx(Modal.Backdrop, { children: _jsx(Modal.Container, { children: _jsxs(Modal.Dialog, { className: "sm:max-w-md", children: [_jsx(Modal.CloseTrigger, {}), _jsx(Modal.Header, { children: _jsx(Modal.Heading, { children: "Your apps" }) }), _jsxs(Modal.Body, { children: [isLoading && (_jsx("div", { className: "grid grid-cols-3 gap-2", children: Array.from({ length: 6 }, (_, index) => (_jsxs("div", { className: "flex flex-col items-center gap-2 p-3", children: [_jsx(Skeleton, { className: "size-12 rounded-xl" }), _jsx(Skeleton, { className: "h-3 w-14" })] }, index))) })), !isLoading && error && (_jsx("p", { className: "py-6 text-center text-sm text-danger", children: "Could not load your apps." })), !isLoading && !error && apps.length === 0 && (_jsx("p", { className: "py-6 text-center text-sm text-muted", children: "No other apps yet. Anything this workspace subscribes to shows up here." })), !isLoading && !error && apps.length > 0 && (_jsx(m.div, { className: "grid grid-cols-3 gap-2", variants: { show: { transition: { staggerChildren: 0.04 } } }, initial: "hidden", animate: "show", children: apps.map((app) => (_jsx(m.div, { variants: { hidden: { opacity: 0, y: 8 }, show: { opacity: 1, y: 0, transition: ENTER } }, children: _jsx(AppTile, { app: app }) }, app.serviceId))) }))] }), _jsx(Modal.Footer, { children: _jsx(ConnectBrowseAllLink, {}) })] }) }) })] }) }));
 }
 function ConnectBrowseAllLink() {
     const { appUrl } = useConnect();