@cosmoops/connect-sdk 0.3.0 → 0.7.0

package/CHANGELOG.md

@@ -0,0 +1,125 @@
+# Changelog
+
+`@cosmoops/connect-sdk` follows semver, with the 0.x convention that **minor
+versions may carry breaking changes** and patch versions never do.
+
+## 0.6.0
+
+### Added
+
+- **`ConnectAppShell`** - the application frame every service platform was
+  otherwise writing by hand: a collapsible sidebar, a top bar carrying the app
+  launcher and the account menu, a mobile drawer below `md`, and your pages in
+  the middle. Each platform passes `name`, `icon` and `nav`; the lockup, the
+  rail geometry, the active-route treatment and the chrome come from one
+  place, which is what keeps a family of platforms looking like one product.
+
+  It mounts `ConnectAccessGate` around `children` by default. That is a
+  deliberate default rather than a convenience: the shell is exactly the "wrap
+  your app content once" place that gate asks for, and a platform that ships a
+  shell and forgets the gate is a platform where a suspended workspace keeps
+  working. The chrome is never gated, and routes that *resolve* a block -
+  your pricing page - are flagged `gateExempt: true` on the nav item itself,
+  so the exemption lives next to the route rather than in a second list that
+  has to be kept in step.
+
+- **`ConnectSideNav`** - the sidebar's nav column on its own, for an app that
+  already has chrome it likes. Sections, one level of children, and the same
+  active-route resolution the shell uses.
+
+- **The nav model as data**: `ConnectNav` / `ConnectNavItem` /
+  `ConnectNavSection` types plus `normalizeNav`, `flattenNav`, `normalizePath`,
+  `resolveActivePath`, `isNavItemActive` and `gateExemptPaths`. Pure functions
+  over plain data, exported because a breadcrumb or a page title derived from
+  your own nav should not be able to disagree with what the rail highlights.
+
+- **`useActivePath`** - the current path, from your router when you pass one
+  and from the browser when you don't.
+
+  Routing is a prop throughout (`renderLink`), because this package ships into
+  any React app and cannot import `next/link`. The default is a plain `<a>`.
+  Uncontrolled, `useActivePath` patches `history.pushState`/`replaceState` to
+  dispatch an event - neither fires one, so a client-side router moves the
+  address bar and tells nothing outside itself, and a sidebar reading
+  `location.pathname` would highlight the route the page first loaded on
+  forever. Pass `activePath` (Next: `usePathname()`) and none of that runs.
+
+## 0.5.0
+
+### Breaking
+
+- **`react` and `react-dom` peers raised to `>=19`** (from `>=18`). Both stay
+  `optional` - a `/server`-only consumer still needs neither - but `/next`'s
+  `getConnectSession()` now imports `react`'s `cache()` unconditionally,
+  which React 18 doesn't export. Every current App Router project is already
+  on 19; this only bites a project still pinned to 18.
+
+### Added
+
+- **`getConnectSession()` is now memoized per request.** The plain,
+  zero-argument call - the one every page, layout and Server Action actually
+  uses - is wrapped in React's `cache()`, so calling it from a layout *and*
+  the page beneath it costs one round trip to Connect, not two. Passing an
+  explicit `request`, `client` or `session` still bypasses the cache and
+  always makes a live call, as before.
+- **`requireConnectSession()`** - `getConnectSession()` plus the
+  `if (!session) redirect(...)` every integration was writing by hand.
+  Redirects to `/api/connect/signin` (or `signInPath`) when signed out,
+  optionally appending `next`. See "Authentication & authorization" in the
+  docs for where role/entitlement checks still belong - this only covers the
+  "is anyone signed in" half.
+
+## 0.4.0
+
+### Breaking
+
+- **`ConnectUser.photoUrl` is a new required field.** Additive for anything
+  *reading* a `ConnectUser`, breaking for anything *constructing* one - a test
+  fixture or a hand-rolled mock will stop type-checking until it sets
+  `photoUrl: string | null`. Nothing else about the type changed.
+
+  Connect has always stored a profile picture; it was simply never carried on
+  the wire, so `<ConnectUserMenu>` showed initials for every account no matter
+  what the member had set. It now flows through `/sso/token` and `/sso/user`.
+
+### Added
+
+- **`<ConnectAccessGate>` and `useConnectAccessGate()`** - one gate composing
+  the four states a partner actually needs, in priority order: workspace
+  suspended, no subscription, onboarding approval pending, and a dismissible
+  payment-due banner during a dunning retry. Replaces hand-assembling
+  `ConnectReadinessGate` + `ConnectSubscriptionGate` and deciding the ordering
+  yourself.
+
+  Mount it once around your app's content, but **carve out your own plans and
+  pricing routes** - its "Choose a plan" state is where blocked customers are
+  sent, so gating that page too traps them. See the component's doc comment.
+
+- **`<ConnectProvider silentSignIn>`** - OIDC silent authentication. A visitor
+  already signed into Connect who has authorised your app before is signed in
+  with no click and no screen. Off by default: it costs one full-page redirect
+  on the first load of a signed-out visit, and is attempted at most once per
+  tab.
+
+  First contact still shows Connect's consent screen once - that grant is
+  exactly what makes every later visit silent.
+
+- `ReadinessBlockerCode` gains `organization_suspended` and
+  `payment_retry_pending`; `ReadinessBlocker` gains an optional `graceEndsAt`
+  carrying the dunning-suspension deadline, so a payment-due warning can show a
+  real countdown instead of a bare "something failed".
+
+- `identity.authorizeUrl({ prompt })` accepts `"none"` alongside `"create"`.
+
+### Fixed
+
+- `ConnectUserMenu` renders the member's actual profile picture, falling back
+  to initials while it loads or if they have none.
+- Panels inside the account modal shared one elevation and one icon-medallion
+  spec; the destination tiles and session list previously used a fill that is
+  the *same lightness* as the modal itself in both light and dark, so they read
+  as hairline outlines beside a solid identity card.
+- `theme.css` now defines `--default` and `--surface-tertiary`. Without them,
+  every `secondary`/`tertiary` Button and default Chip fell back to
+  `@heroui/styles`' stock cool-grey ramp while the rest of the palette sat on a
+  warm one - close enough to read as a mistake rather than a choice.

package/README.md

@@ -25,7 +25,7 @@ Browser  ──►  your backend  ──►  Connect
 
 ## Server setup
 
-One credential does three jobs — the API key plaintext from your service's Setup tab is also your OAuth2 `client_secret` and the key your `id_token` is signed with. Revoking it revokes all three.
+One credential does three jobs — the API key plaintext from your service's Integration tab is also your OAuth2 `client_secret` and the key your `id_token` is signed with. Revoking it revokes all three.
 
 ```ts
 import { ConnectClient } from "@cosmoops/connect-sdk/server";
@@ -87,6 +87,49 @@ if (!serviceRole.granted.includes("invoice:write")) return forbidden();
 await connect.identity.logout(sessionToken);
 ```
 
+## Sign returning visitors in with no click
+
+A visitor already signed into Connect should not have to press "Sign in"
+again. OIDC calls this silent authentication, and on `./next` it is one prop:
+
+```tsx
+<ConnectProvider silentSignIn>
+```
+
+On the first load of a signed-out visit the browser makes one round trip to
+Connect with `prompt=none`. If they have a Connect session **and** have
+authorised your app before, they come back signed in having seen nothing. If
+not, they come back signed out — no error, no screen, your normal signed-out
+UI a beat later.
+
+Rolling it yourself is the same flow with `prompt: "none"`:
+
+```ts
+redirect(connect.identity.authorizeUrl({ redirectUri, state, prompt: "none" }));
+```
+
+Three things to get right, all handled for you by `./next`:
+
+- **`prompt=none` never shows a login screen — that is its contract.** Use it
+  to *resume* a session, never to start one. Sending a genuinely signed-out
+  visitor through it in a loop is the classic way to build a redirect loop.
+- **`login_required` from a silent attempt is not the `login_required` above.**
+  The retry in step 2 is right for an interactive sign-in and wrong here: it
+  escalates a quiet "nobody home" into a forced login. Track which kind of
+  attempt is in flight.
+- **Attempt it at most once per tab.** A visitor with no Connect session will
+  answer the same way on every page load; without a marker, every navigation
+  pays a full redirect.
+
+**First contact still shows Connect's consent screen once.** That grant is
+exactly what makes every later visit silent, and it is per user, per client —
+so `consent_required` means "they have never authorised you", not "something
+broke". Treat all three of `login_required`, `consent_required` and
+`interaction_required` as "carry on signed out".
+
+It costs a full-page redirect on that first load, which is why it is off by
+default: worth it for an app shell, less so for a marketing page.
+
 ## Gate on entitlements
 
 ```ts
@@ -149,6 +192,7 @@ try {
 | `logs` | `write` |
 | `apps` | `list` |
 | `sessions` | `list` · `revoke` · `revokeOthers` |
+| `integrations` | `list` · `initiateConnect` · `disconnect` · `execute` |
 
 ### Attributing a log to a user
 
@@ -215,7 +259,7 @@ cookie, `/session`, `/entitlements`, `/plans`, `/addons`, `/apps`, `/sessions`,
 | `CONNECT_SESSION_COOKIE` | no | session cookie name |
 
 Register `{your origin}/api/connect/callback` as a redirect URI in the service's
-Setup tab — the one step this cannot do for you.
+Integration tab — the one step this cannot do for you.
 
 No `next.config.ts` changes needed, including `transpilePackages`: `dist/` is
 already ES2022 with `"use client"` hoisted, so Turbopack and webpack both
@@ -235,9 +279,26 @@ export default async function DashboardPage() {
 }
 ```
 
+Or skip the check-and-redirect entirely — `requireConnectSession()` does both:
+
+```tsx
+import { requireConnectSession } from "@cosmoops/connect-sdk/next";
+
+export default async function DashboardPage() {
+  const session = await requireConnectSession(); // UserResponse — redirects if signed out
+  return <h1>{session.user.organizationName}</h1>;
+}
+```
+
 Pass a `Request` — `getConnectSession(request)` — anywhere `next/headers` does
 not exist: a framework-agnostic handler, a custom server, a test.
 
+Both are memoized per request when called with no arguments (React's
+`cache()`), so a layout reading the session for a nav avatar and the page
+beneath it reading it again for a role check share one round trip to Connect,
+not two. An explicit `request`, `client` or `session` argument bypasses the
+cache and always makes a live call.
+
 It reads `cookies()` transitively, so under `cacheComponents` it belongs inside
 a `<Suspense>` boundary like any other request-scoped read. A page that awaits
 it above every boundary gives up its static shell.
@@ -344,11 +405,16 @@ that URL yourself instead.
 
 ```tsx
 import {
+  ConnectAppShell,
   ConnectLoginButton, ConnectRegisterButton,
   ConnectUserMenu, ConnectAppsGrid, ConnectPlans,
 } from "@cosmoops/connect-sdk/client";
 
-// Top bar — the pair swaps automatically on sign-in state
+// The whole frame — sidebar, top bar, access gate. See "App shell" below.
+<ConnectAppShell name="Dispatch" nav={nav}>{children}</ConnectAppShell>
+
+// Or the pieces, if you already have a layout. The pair swaps automatically
+// on sign-in state.
 <ConnectAppsGrid />
 <ConnectLoginButton />
 <ConnectUserMenu />
@@ -359,12 +425,15 @@ import {
 
 | Component | What it does |
 | --- | --- |
+| `ConnectAppShell` | **The whole application frame** — collapsible sidebar, top bar with the launcher and account menu, and your pages in the middle. Mounts `ConnectAccessGate` for you. |
+| `ConnectSideNav` | The sidebar's nav column on its own — sections, one level of children, active-route highlight — for an app that already has its own chrome. |
 | `ConnectLoginButton` · `ConnectRegisterButton` | "Continue with Connect", in the shape people know from Google. Render nothing when signed in. |
 | `ConnectUserMenu` | Avatar, name, workspace. Profile, Manage subscription and Open Connect each open Connect in a new tab; Sign out acts in place. Renders nothing when signed out. |
 | `ConnectAppsGrid` | Google-style launcher — grid icon opening a modal of every app this workspace can open. |
 | `ConnectPlans` | Monthly/annual toggle, features, add-ons, live discount, coupon field, and the subscribe / upgrade / downgrade / cancel flow. |
 | `ConnectPlansPage` | A whole `/plans` page — readiness banner, current subscription, and the grid. What `connect-sdk init` scaffolds. |
 | `ConnectSubscribeDialog` | The review step `ConnectPlans` opens — plan, GST, what happens to the current cycle. Exported so you can drive the flow from your own pricing page. |
+| `ConnectAccessGate` | **The one gate to mount if you mount one.** Composes suspended / no-plan / onboarding-pending / payment-due into a single priority-ordered decision. Wrap your app content once. |
 | `ConnectSubscriptionGate` | Renders your module for a subscribed workspace, and `ConnectNoSubscriptionCard` for everyone else. Never flashes the upsell while loading. |
 | `ConnectNoSubscriptionCard` · `ConnectSubscriptionCard` | The same slot, unsubscribed and subscribed. Plan, status, renewal date, seats, and one way into Connect. |
 | `ConnectReadinessBanner` · `ConnectReadinessGate` | Every gate between this workspace and your service — KYC, payment method, seat headroom — each with the Connect screen that fixes it. |
@@ -377,7 +446,7 @@ import {
 
 ### Hooks
 
-`useConnect` · `useConnectUser` · `useConnectEntitlements` · `useConnectPlans` · `useConnectApps` · `useConnectAddonUsage` · `useConnectSessions` · `useConnectResource` · `useConnectFeature` · `useConnectCheckout`
+`useConnect` · `useConnectUser` · `useActivePath` · `useConnectAccessGate` · `useConnectEntitlements` · `useConnectPlans` · `useConnectApps` · `useConnectAddonUsage` · `useConnectSessions` · `useConnectResource` · `useConnectFeature` · `useConnectCheckout`
 
 ### Metering
 
@@ -396,13 +465,59 @@ The catalogue read (`useConnectPlans`, `<ConnectPlans />`) reports `features` as
 
 ### Gates
 
+Most apps want **one** gate around everything, and finer ones inside it.
+
+```tsx
+// Mount once, around your app's content — not around your header.
+<ConnectAccessGate>
+  <YourApp />
+</ConnectAccessGate>
+```
+
+`ConnectAccessGate` answers "can this workspace use my app right now" in one
+priority-ordered pass, so you are not left assembling the pieces and choosing
+the order yourself:
+
+| State | What renders |
+| --- | --- |
+| `suspended` | A hard stop. Nothing the customer does clears it — only a Connect admin reactivating the workspace. |
+| `no_subscription` | "Choose a plan", linking to Connect's subscribe page for your service. |
+| `onboarding_pending` | Waiting on a reviewer. No action offered, because there is none. |
+| `blocked` | Any other blocking readiness code — verification, audience, seats — each with its own fix. |
+| `payment_retry` | **Your app still renders.** A dismissible banner counts down to the dunning deadline. |
+| `clear` | Your app, nothing else. |
+
+**Carve out your own plans/pricing routes.** The `no_subscription` card sends
+people to choose a plan; if the gate also covers the page they land on, they
+are trapped. The SDK cannot do this for you — it imports nothing from `next`
+and so cannot know your router:
+
+```tsx
+const EXEMPT = new Set(["/plans", "/pricing"]);
+const gated = !EXEMPT.has(usePathname());
+
+<main>{gated ? <ConnectAccessGate>{children}</ConnectAccessGate> : children}</main>
+```
+
+For per-state UI, call the hook instead of overriding `fallback`:
+
+```tsx
+const { state, blocker, paymentRetry } = useConnectAccessGate();
+```
+
+Signed-out renders `children`, deliberately — unlike the gates below. None of
+those states describes a signed-out visitor, and a gate around your whole app
+must not hide a public landing page.
+
+The narrower gates still exist for gating *within* a cleared workspace:
+
 ```tsx
 <ConnectReadinessBanner />                       {/* KYC, payment method, seats — each with a fix */}
 <ConnectSubscriptionGate><Dashboard /></ConnectSubscriptionGate>
 <ConnectFeatureGate feature="advanced_reports"><Reports /></ConnectFeatureGate>
 ```
 
-All three render `loading` — never the fallback — while the answer is unknown, so a paying customer is never flashed an upsell for something they already have.
+All of them render `loading` — never the fallback — while the answer is unknown, so a paying customer is never flashed an upsell for something they already have.
 
 **They are UX gates, not security boundaries.** Everything they read reaches your own origin and a browser can ignore it. The authoritative check is on your server: `client.entitlements.getReadiness(orgId)` and `client.entitlements.hasFeature(orgId, feature)`.
 
@@ -458,6 +573,100 @@ const checkout = useConnectCheckout();
 
 Cancelling uses the same machinery via `buildCancelUrl`. There is no *resume*: Connect has no uncancel path, so a subscription already set to cancel gets a statement of when access ends, not a button that cannot work.
 
+### App shell
+
+```tsx
+"use client";
+import Link from "next/link";
+import { usePathname } from "next/navigation";
+import { ConnectAppShell } from "@cosmoops/connect-sdk/client";
+import { LayoutDashboard, Receipt, Settings, 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: "Shipments", href: "/shipments", icon: <Truck className="size-5" /> },
+        {
+          title: "Workspace",
+          items: [
+            {
+              label: "Settings",
+              href: "/settings",
+              icon: <Settings className="size-5" />,
+              items: [
+                { label: "Members", href: "/settings/members" },
+                { label: "Billing", href: "/settings/billing" },
+              ],
+            },
+            { label: "Plans", href: "/plans", icon: <Receipt className="size-5" />, gateExempt: true },
+          ],
+        },
+      ]}
+    >
+      {children}
+    </ConnectAppShell>
+  );
+}
+```
+
+That is the entire layout of a service platform. Everything that should look
+identical across the family — the lockup, the rail geometry, the active-route
+treatment, the app launcher, the account menu, the mobile drawer — comes from
+here; only `name`, `icon` and `nav` differ per platform.
+
+**Routing is a prop.** The SDK ships into any React app and cannot import
+`next/link`, so `renderLink` is how your router gets involved; the default is a
+plain `<a>`, which works everywhere and costs a full page load. Pass
+`activePath` from your router too (`usePathname()`) — without it the nav reads
+`window.location` and patches `history.pushState` to hear about client-side
+navigations, which is guesswork your router never has to do.
+
+**The access gate is on by default.** `ConnectAppShell` is exactly the "wrap
+your app content once" place `ConnectAccessGate` asks for, so it mounts one
+around `children` — an app that ships a shell and forgets the gate is an app
+that lets a suspended workspace keep working. The chrome is never gated: the
+sidebar, the lockup, the account menu and sign-out stay reachable in every
+blocked state. Routes that resolve a block rather than needing one — your
+pricing page — are flagged where they are declared:
+
+```tsx
+{ label: "Plans", href: "/plans", gateExempt: true }
+```
+
+Gate a route any other way and a customer with no subscription reaches the
+page that sells them one, and is told to choose a plan. Pass `gate={false}` to
+opt out entirely, or `gateExemptRoutes` for a path that is not in the sidebar
+at all.
+
+Other things worth knowing:
+
+- **The rail collapses to icons** and remembers the choice per browser
+  (`localStorage`). Drive it yourself with `collapsed` + `onCollapsedChange`,
+  or pin it open with `collapsible={false}`.
+- **Below `md` there is no rail**, only a drawer behind the top bar's menu
+  button — a 64px icon strip on a phone is a worse drawer, not a smaller one.
+- **Children unfold only on the branch you are on.** A sidebar that opens
+  every branch at once is a sitemap.
+- **No `isSignedIn` branch, in here or in yours.** The auth buttons render
+  nothing once a session exists, the account menu renders nothing without one,
+  and the launcher renders nothing when signed out.
+- `title`, `headerActions`, `sidebarFooter` and `footer` are slots;
+  `contentClassName` replaces the content pane's default max-width and
+  padding.
+- `theme` / `onThemeChange` pass straight through to `ConnectUserMenu` — the
+  SDK has no theme provider of its own, deliberately.
+
+`ConnectSideNav` is the nav column alone, for an app with chrome it already
+likes. `resolveActivePath` and `isNavItemActive` are the same pure functions
+the rail highlights with, exported so a breadcrumb or a document title derived
+from your nav cannot disagree with it.
+
 ### Logo
 
 ```tsx
@@ -479,7 +688,7 @@ Each platform passes only what differs — `name` and `icon`. Mark geometry, wor
 
 One shared **HeroUI v3** theme for every service platform. The components paint with semantic tokens only — `accent`, `muted`, `surface`, `separator`, `danger` — never a hardcoded colour, so one edit to the theme restyles all of them everywhere at once. To diverge on brand, redefine individual tokens *after* the import rather than forking the file.
 
-Requires `@heroui/react` and `lucide-react` as peers (optional — server-only consumers need neither).
+Requires `@heroui/react`, `lucide-react` and `motion` as peers (optional — server-only consumers need none of them). `motion` drives the components' entrance and state transitions, and respects `prefers-reduced-motion`.
 
 ### Why payment happens on Connect
 

package/dist/cjs/cli/doctor.js

@@ -162,8 +162,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 application's Integration tab in Connect.`
+                : `Not found in .env.local or the environment. Both values are in your application's Integration tab in Connect.`,
         };
     });
 }
@@ -176,7 +176,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 application's Integration tab - including the deployed origin, not just http://localhost:3000.",
     };
 }
 const MARKER = { pass: "  ok  ", warn: " note ", fail: " FAIL " };

package/dist/cjs/cli/init.js

@@ -44,7 +44,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 application's Integration tab.
 CONNECT_API_KEY=
 CONNECT_CLIENT_ID=
 `;
@@ -111,7 +111,7 @@ function runInit(argv = []) {
         console.log(`  ${marker}  ${(0, node_path_1.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 application'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.
@@ -137,7 +137,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.
+     application'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/cjs/client/components/access-gate.js

@@ -0,0 +1,162 @@
+"use client";
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useConnectAccessGate = useConnectAccessGate;
+exports.ConnectAccessGate = ConnectAccessGate;
+const jsx_runtime_1 = require("react/jsx-runtime");
+const react_1 = require("react");
+const lucide_react_1 = require("lucide-react");
+const react_2 = require("@heroui/react");
+const helpers_js_1 = require("../../helpers.js");
+const provider_js_1 = require("../provider.js");
+const motion_js_1 = require("./motion.js");
+const readiness_js_1 = require("./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`.
+ */
+function useConnectAccessGate() {
+    const { session, isLoading: sessionLoading } = (0, provider_js_1.useConnect)();
+    const { data, isLoading: entitlementsLoading } = (0, provider_js_1.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 = (0, helpers_js_1.blockingBlockers)(readiness);
+    const suspended = blocking.find((b) => b.code === "workspace_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.
+ */
+function ConnectAccessGate({ children, fallback, loading, className }) {
+    const gate = useConnectAccessGate();
+    if (gate.state === "loading") {
+        return (0, jsx_runtime_1.jsx)(jsx_runtime_1.Fragment, { children: loading ?? (0, jsx_runtime_1.jsx)(react_2.Skeleton, { className: `h-32 rounded-xl ${className ?? ""}` }) });
+    }
+    if (gate.state === "signed_out" || gate.state === "clear") {
+        return (0, jsx_runtime_1.jsx)(jsx_runtime_1.Fragment, { children: children });
+    }
+    if (gate.state === "payment_retry") {
+        return ((0, jsx_runtime_1.jsxs)(jsx_runtime_1.Fragment, { children: [gate.paymentRetry && (0, jsx_runtime_1.jsx)(PaymentRetryBanner, { blocker: gate.paymentRetry, className: className }), children] }));
+    }
+    return ((0, jsx_runtime_1.jsx)(jsx_runtime_1.Fragment, { children: fallback ?? (0, jsx_runtime_1.jsx)(AccessGateFallback, { state: gate.state, blocker: gate.blocker, className: className }) }));
+}
+function AccessGateFallback({ state, blocker, className, }) {
+    if (state === "no_subscription") {
+        return ((0, jsx_runtime_1.jsx)(GateCard, { icon: lucide_react_1.CreditCard, iconClassName: "text-accent", title: "Choose a plan to continue", message: blocker?.message ?? "This workspace isn't subscribed to this application yet.", actionLabel: "See plans", resolveUrl: blocker?.resolveUrl ?? null, className: className }));
+    }
+    if (state === "suspended") {
+        return ((0, jsx_runtime_1.jsx)(GateCard, { icon: lucide_react_1.Ban, iconClassName: "text-danger", title: "Workspace suspended", message: blocker?.message ?? "This workspace has been suspended.", resolveUrl: null, className: className }));
+    }
+    if (state === "onboarding_pending") {
+        return ((0, jsx_runtime_1.jsx)(GateCard, { icon: lucide_react_1.Clock, iconClassName: "text-muted", title: "Waiting on approval", message: blocker?.message ?? "This workspace is waiting on approval before it can use this application.", 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 ((0, jsx_runtime_1.jsx)(react_2.Card, { className: className, children: (0, jsx_runtime_1.jsx)(react_2.Card.Content, { className: "py-6", children: (0, jsx_runtime_1.jsx)(readiness_js_1.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 ((0, jsx_runtime_1.jsx)(motion_js_1.MotionProvider, { children: (0, jsx_runtime_1.jsx)(motion_js_1.m.div, { initial: { opacity: 0, y: -6 }, animate: { opacity: 1, y: 0 }, transition: motion_js_1.ENTER, children: (0, jsx_runtime_1.jsxs)(react_2.Card, { className: className, children: [(0, jsx_runtime_1.jsxs)(react_2.Card.Header, { children: [(0, jsx_runtime_1.jsxs)("div", { className: "flex items-center gap-2", children: [(0, jsx_runtime_1.jsx)(Icon, { className: `size-5 shrink-0 ${iconClassName}`, "aria-hidden": "true" }), (0, jsx_runtime_1.jsx)(react_2.Card.Title, { children: title })] }), (0, jsx_runtime_1.jsx)(react_2.Card.Description, { children: message })] }), resolveUrl && ((0, jsx_runtime_1.jsx)(react_2.Card.Footer, { children: (0, jsx_runtime_1.jsxs)(react_2.Button, { variant: "primary", onPress: () => window.open(resolveUrl, "_blank", "noopener,noreferrer"), children: [actionLabel ?? "Resolve on Connect", (0, jsx_runtime_1.jsx)(lucide_react_1.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] = (0, react_1.useState)(() => dismissKey !== null && typeof window !== "undefined" && window.localStorage.getItem(dismissKey) === "1");
+    if (dismissed)
+        return null;
+    return ((0, jsx_runtime_1.jsx)(motion_js_1.MotionProvider, { children: (0, jsx_runtime_1.jsxs)(motion_js_1.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: motion_js_1.ENTER, children: [(0, jsx_runtime_1.jsxs)("span", { className: "flex items-center gap-2", children: [(0, jsx_runtime_1.jsx)(lucide_react_1.AlertTriangle, { className: "size-4 shrink-0", "aria-hidden": "true" }), blocker.message, blocker.graceEndsAt && ` Resolve by ${formatDate(blocker.graceEndsAt)} to avoid losing access.`] }), (0, jsx_runtime_1.jsxs)("div", { className: "flex items-center gap-2", children: [blocker.resolveUrl && ((0, jsx_runtime_1.jsxs)(react_2.Button, { variant: "secondary", onPress: () => window.open(blocker.resolveUrl, "_blank", "noopener,noreferrer"), children: ["Resolve payment", (0, jsx_runtime_1.jsx)(lucide_react_1.ExternalLink, { className: "size-3.5" })] })), (0, jsx_runtime_1.jsx)(react_2.Button, { variant: "tertiary", isIconOnly: true, "aria-label": "Dismiss", onPress: () => {
+                                setDismissed(true);
+                                if (dismissKey && typeof window !== "undefined")
+                                    window.localStorage.setItem(dismissKey, "1");
+                            }, children: (0, jsx_runtime_1.jsx)(lucide_react_1.X, { className: "size-4" }) })] })] }) }));
+}