@cosmoops/connect-sdk 0.24.0 → 0.25.0

package/CHANGELOG.md

@@ -3,6 +3,91 @@
 `@cosmoops/connect-sdk` follows semver, with the 0.x convention that **minor
 versions may carry breaking changes** and patch versions never do.
 
+## 0.25.0
+
+### Changed
+
+- **`getConnectSession()` no longer reports a failed read as "signed out".**
+  It returned `null` for *every* failure, and `null` is what makes
+  `requireConnectSession()` redirect to sign-in - so a rate-limited or
+  unreachable Connect logged a signed-in user out, and the OAuth round trip
+  that followed spent more calls against the same exhausted budget and failed
+  again on the way back. A login loop that could only end when the rate-limit
+  window rolled. Two developers hit it; production logs showed 120 429s on
+  `/sso/user` in a day, arriving in bursts of fifteen inside one second,
+  because a partner layout that reads the session is called once per
+  prefetched route shell.
+
+  `null` now means **there is no session** - no cookie, or one Connect reports
+  as expired, revoked, or issued to another application, which are exactly the
+  cases where sending someone back through sign-in is right. Everything else
+  throws. This is the breaking part: a guard written as
+  `const s = await getConnectSession(); if (!s) redirect(…)` will now surface
+  a transient failure to the nearest error boundary rather than silently
+  signing the visitor out. That is the intended behaviour - an error boundary
+  is recoverable and truthful, a spurious sign-out is neither - but it is a
+  behaviour change, which is why this is a minor rather than a patch.
+
+- **`<ConnectProvider>` keeps the session it already has when a refresh
+  fails.** It used to replace whatever was known with a signed-out session on
+  any error. On a first load that is right - something has to render rather
+  than skeletons forever - but on a refresh it meant one dropped or throttled
+  request logged the user out of the UI, and the host app's own guards then
+  acted on it. `error` is still set either way.
+
+### Fixed
+
+- **`POST /sso/user` never retried a 429.** The transport has honoured
+  `Retry-After` with exponential backoff all along, but only for requests it
+  considered idempotent - and that test keyed on the verb, so it excluded
+  every `POST`. `/sso/user` is a `POST` because its input is a session token
+  that must not sit in a URL; it writes nothing, and it is the most-called
+  endpoint on the platform. It was therefore the one endpoint that could never
+  ride out a throttle. `RequestSpec` gains `idempotent` for reads shaped this
+  way. `POST /sso/token` deliberately does not set it: it consumes a one-time
+  authorization code, and a replay is an exchange of a code that no longer
+  exists.
+
+- **"useInsertionEffect must not schedule updates." on every navigation.**
+  `useActivePath`'s uncontrolled fallback patches
+  `history.pushState`/`replaceState` so a shell with no `activePath` can see a
+  client-side navigation, and it dispatched its `connect:locationchange`
+  event synchronously from inside the patched method. Next's App Router
+  commits its history entry from a `useInsertionEffect` (`HistoryUpdater`),
+  so the listener - and the re-render `useSyncExternalStore` forces from it -
+  landed in the middle of that phase, which React refuses: a console error on
+  every navigation in any app that lets the rail resolve its own active path.
+
+  The dispatch is now deferred to a microtask, which runs once the commit's
+  stack has unwound. `location.pathname` already holds the new value by then,
+  so the snapshot is unchanged and the highlight still moves on the same
+  commit; only the scheduling moved. A shell that passes `activePath` never
+  ran any of this and was never affected.
+
+## 0.24.1
+
+### Fixed
+
+- **`<ConnectConfirmDialog />` never opened.** Its trigger was wrapped in
+  `Modal.Trigger`, which renders a `div role="button"` inside React Aria's
+  `Pressable` and depends on a plain `onClick` bubbling up to it. A React Aria
+  button nested inside - which every real trigger is, including HeroUI's
+  `<Button>` - calls `e.stopPropagation()` in its own `usePress` click
+  handler, so the click never arrived. Nothing threw and nothing warned; the
+  press was simply eaten, and every confirmation in every app built on this
+  SDK was inert. Twelve of them across the two reference apps: each delete
+  confirmation in the CRM, and each in the club app.
+
+  The trigger is now a direct child of the `Modal` root, which is React Aria's
+  `DialogTrigger`. Its `PressResponder` picks the trigger up directly, so
+  there is no nested pressable and no propagation to lose.
+
+  No call site changes. The prop's contract is now stated the right way round:
+  the trigger **must** be a pressable - a HeroUI `Button`, or anything else
+  built on React Aria's `useButton`. A non-pressable element (a bare `<span>`)
+  used to be the only thing that worked and now does not; nothing shipped
+  passes one.
+
 ## 0.24.0
 
 ### Fixed

package/dist/cjs/client/components/confirm-dialog.js

@@ -19,11 +19,19 @@ const react_2 = require("@heroui/react");
  * rejection is caught here rather than escaping - an error thrown out of an
  * async transition reaches the nearest error boundary and takes the page down.
  *
- * The anatomy is HeroUI's: `Modal.Backdrop` owns the open state,
- * `Modal.Container` the sizing, `Modal.Dialog` the focus trap. The trigger
- * goes inside `Modal.Trigger`, which *is* a React Aria button - so pass a
- * plain element, never a `<Button>`, or the nested button swallows the press
- * and the dialog silently never opens.
+ * The anatomy is HeroUI's: the `Modal` root owns the open state,
+ * `Modal.Container` the sizing, `Modal.Dialog` the focus trap. **The trigger
+ * is a direct child of the root**, never wrapped in `Modal.Trigger`.
+ *
+ * That wrapping is what this component used to do, and it meant the dialog
+ * never opened for any caller passing a `<Button>` - which was all of them.
+ * `Modal.Trigger` renders a `div role="button"` inside React Aria's
+ * `Pressable` and relies on a plain `onClick` bubbling up to it; a React Aria
+ * button nested inside calls `e.stopPropagation()` in its own `usePress`
+ * click handler, so the click never arrives. Nothing failed loudly - the
+ * press was simply eaten. The root is `DialogTrigger`, whose `PressResponder`
+ * the trigger registers with directly, so there is no nesting and no
+ * propagation to lose.
  */
 function ConnectConfirmDialog({ trigger, title, description, confirmLabel = "Confirm", cancelLabel = "Cancel", tone = "danger", onConfirm, }) {
     const [isOpen, setIsOpen] = (0, react_1.useState)(false);
@@ -36,5 +44,5 @@ function ConnectConfirmDialog({ trigger, title, description, confirmLabel = "Con
             // caller, which owns the toast and the rollback.
         });
     };
-    return ((0, jsx_runtime_1.jsxs)(jsx_runtime_1.Fragment, { children: [(0, jsx_runtime_1.jsx)(react_2.Modal.Trigger, { onClick: () => setIsOpen(true), children: trigger }), (0, jsx_runtime_1.jsx)(react_2.Modal.Backdrop, { isOpen: isOpen, onOpenChange: setIsOpen, children: (0, jsx_runtime_1.jsx)(react_2.Modal.Container, { size: "sm", children: (0, jsx_runtime_1.jsxs)(react_2.Modal.Dialog, { children: [(0, jsx_runtime_1.jsx)(react_2.Modal.CloseTrigger, { onPress: () => setIsOpen(false) }), (0, jsx_runtime_1.jsx)(react_2.Modal.Header, { children: (0, jsx_runtime_1.jsx)(react_2.Modal.Heading, { children: title }) }), description && ((0, jsx_runtime_1.jsx)(react_2.Modal.Body, { children: (0, jsx_runtime_1.jsx)("p", { className: "text-sm text-muted", children: description }) })), (0, jsx_runtime_1.jsxs)(react_2.Modal.Footer, { children: [(0, jsx_runtime_1.jsx)(react_2.Button, { variant: "secondary", onPress: () => setIsOpen(false), children: cancelLabel }), (0, jsx_runtime_1.jsx)(react_2.Button, { variant: tone === "danger" ? "danger" : "primary", onPress: confirm, children: confirmLabel })] })] }) }) })] }));
+    return ((0, jsx_runtime_1.jsxs)(react_2.Modal, { isOpen: isOpen, onOpenChange: setIsOpen, children: [trigger, (0, jsx_runtime_1.jsx)(react_2.Modal.Backdrop, { children: (0, jsx_runtime_1.jsx)(react_2.Modal.Container, { size: "sm", children: (0, jsx_runtime_1.jsxs)(react_2.Modal.Dialog, { children: [(0, jsx_runtime_1.jsx)(react_2.Modal.CloseTrigger, { onPress: () => setIsOpen(false) }), (0, jsx_runtime_1.jsx)(react_2.Modal.Header, { children: (0, jsx_runtime_1.jsx)(react_2.Modal.Heading, { children: title }) }), description && ((0, jsx_runtime_1.jsx)(react_2.Modal.Body, { children: (0, jsx_runtime_1.jsx)("p", { className: "text-sm text-muted", children: description }) })), (0, jsx_runtime_1.jsxs)(react_2.Modal.Footer, { children: [(0, jsx_runtime_1.jsx)(react_2.Button, { variant: "secondary", onPress: () => setIsOpen(false), children: cancelLabel }), (0, jsx_runtime_1.jsx)(react_2.Button, { variant: tone === "danger" ? "danger" : "primary", onPress: confirm, children: confirmLabel })] })] }) }) })] }));
 }

package/dist/cjs/client/provider.js

@@ -152,13 +152,34 @@ function ConnectProvider({ clientId = "", basePath = "/api/connect", redirectUri
             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, role: null, permissions: [], staff: false, audience: null },
-                error: cause instanceof Error ? cause.message : "Could not reach Connect",
-            });
+            const message = cause instanceof Error ? cause.message : "Could not reach Connect";
+            /*
+             * **A failed read never downgrades a session we already have.**
+             *
+             * This used to replace whatever was known with a signed-out session on
+             * every failure. On a first load that is right - something has to render
+             * rather than skeletons forever - but on a *refresh* it meant one
+             * throttled or dropped request logged the user out of the UI, and the
+             * host app's own guards then acted on that.
+             *
+             * Keeping the last known session is the honest reading: the bridge could
+             * not answer, so what we knew a moment ago is still the best answer we
+             * have. `error` is set either way, so an app that wants to surface
+             * "we've lost touch with Connect" still can.
+             */
+            setResult((previous) => previous?.session.user
+                ? { session: previous.session, error: message }
+                : {
+                    session: {
+                        user: null,
+                        subscription: null,
+                        role: null,
+                        permissions: [],
+                        staff: false,
+                        audience: null,
+                    },
+                    error: message,
+                });
         }
     }, [fetchResource]);
     (0, react_1.useEffect)(() => {

package/dist/cjs/client/use-active-path.js

@@ -20,6 +20,17 @@ let patched = false;
  * actually mounted without an `activePath`. Pass `activePath` (Next:
  * `usePathname()`) and none of this runs at all - which is the recommended
  * path for any app that has a router to ask.
+ *
+ * The notification is deferred to a microtask, and that is load-bearing
+ * rather than tidiness. Next's App Router commits its history entry from
+ * inside a `useInsertionEffect` (`HistoryUpdater` calls
+ * `history.pushState`/`replaceState` there), so a synchronous
+ * `dispatchEvent` reaches `useSyncExternalStore`'s listener *during* that
+ * phase and the re-render it forces is refused: React logs
+ * "useInsertionEffect must not schedule updates" on every navigation. A
+ * microtask runs once the commit's stack has unwound, by which point
+ * `location.pathname` already holds the new value, so the snapshot the store
+ * reads is the same one - only the scheduling moves.
  */
 function patchHistory() {
     if (patched || typeof window === "undefined" || typeof window.history === "undefined")
@@ -29,7 +40,7 @@ function patchHistory() {
         const original = window.history[method];
         window.history[method] = function patchedHistoryMethod(...args) {
             const result = original.apply(this, args);
-            window.dispatchEvent(new Event(LOCATION_CHANGE));
+            queueMicrotask(() => window.dispatchEvent(new Event(LOCATION_CHANGE)));
             return result;
         };
     }

package/dist/cjs/next/index.js

@@ -45,6 +45,7 @@ exports.requireConnectSession = requireConnectSession;
 const react_1 = require("react");
 const client_js_1 = require("../server/client.js");
 const handler_js_1 = require("../server/handler.js");
+const errors_js_1 = require("../errors.js");
 /**
  * Plug-and-play wiring for Next.js.
  *
@@ -241,7 +242,34 @@ async function readSession(request, options) {
     try {
         return await (options.client ?? connectClient()).identity.getUser(token);
     }
-    catch {
+    catch (cause) {
+        /*
+         * `null` means **not signed in**, and nothing else.
+         *
+         * This used to be a bare `catch { return null }`, so every failure - a
+         * throttled read, a five-hundred, a network blip - was reported to the
+         * caller as "there is no session here". That is the worst possible lie for
+         * this particular function, because `requireConnectSession` and every
+         * app guard built on it answer "not signed in" by redirecting to sign-in.
+         *
+         * The result was a login loop nobody could escape: a 429 on the session
+         * read bounced a signed-in user to `/signin`, the OAuth round trip spent
+         * *more* calls against the same exhausted bucket, and the app 429'd again
+         * on the way back. It could only clear when the rate-limit window rolled.
+         * Both of the screenshots that reported this show exactly that sequence.
+         *
+         * So only a genuine session failure answers `null`. `isSessionExpired`
+         * covers the whole family the API deliberately collapses into
+         * `invalid_token` - unknown, expired, revoked, or issued to another
+         * application - which are the cases where signing in again is the correct
+         * and only response.
+         *
+         * Everything else throws. A page that cannot reach Connect gets an error
+         * boundary, which is recoverable and truthful; being quietly signed out is
+         * neither.
+         */
+        if (cause instanceof errors_js_1.ConnectError && !cause.isSessionExpired)
+            throw cause;
         return null;
     }
 }
@@ -284,8 +312,18 @@ const cachedAmbientSession = (0, react_1.cache)(async () => {
  * any other request-scoped read - a page that awaits it above every boundary
  * gives up its static shell.
  *
- * Returns `null` for every failure - an expired session and a missing one both
- * mean "not signed in", and a page guard should not need a try/catch.
+ * Returns `null` when there is **no session** - no cookie, or one Connect
+ * reports as expired, revoked or issued to another application. A page guard
+ * needs no try/catch for those, which are the cases where sending someone
+ * back through sign-in is the right answer.
+ *
+ * **It throws on anything else**, and that is deliberate. It previously
+ * swallowed every failure into `null`, so a rate-limited or unreachable
+ * Connect read as "signed out" - and `requireConnectSession` then redirected a
+ * signed-in user to sign-in, whose OAuth round trip spent more of the same
+ * exhausted budget and 429'd again on return. A login loop that could only end
+ * when the rate-limit window rolled. An error boundary is the honest outcome
+ * for "could not ask", and unlike a spurious sign-out it is recoverable.
  *
  * **Memoized per request for the plain, zero-argument call** - the shape
  * every page, layout and Server Action actually uses - via React's `cache()`.

package/dist/cjs/server/client.js

@@ -161,4 +161,4 @@ class ConnectClient {
 }
 exports.ConnectClient = ConnectClient;
 /** Kept in step with `package.json` by `sdk.test.ts`. */
-exports.SDK_VERSION = "0.24.0";
+exports.SDK_VERSION = "0.25.0";

package/dist/cjs/server/http.js

@@ -122,7 +122,9 @@ async function request(options, spec) {
     // `PUT` and `DELETE` are idempotent by definition - replaying one lands the
     // same end state - so they retry like `GET`. `POST` still needs an
     // `Idempotency-Key` to earn it, because a replayed create is a second row.
-    const idempotent = spec.method !== "POST" || headers["idempotency-key"] !== undefined;
+    const idempotent = spec.idempotent === true ||
+        spec.method !== "POST" ||
+        headers["idempotency-key"] !== undefined;
     const attempts = idempotent ? options.maxRetries + 1 : 1;
     let lastError;
     for (let attempt = 0; attempt < attempts; attempt++) {

package/dist/cjs/server/resources/identity.js

@@ -179,7 +179,14 @@ class IdentityResource {
      * `authorizeUrl()`.
      */
     async getUser(sessionToken) {
-        const wire = await this.post("/sso/user", { session_token: sessionToken });
+        /*
+         * `idempotent` because it is: this asks who a session token belongs to and
+         * writes nothing. Without it a 429 here reached the caller on the first
+         * attempt, and the transport's `Retry-After` backoff - which exists
+         * exactly for this - never ran, because the rule keyed on the verb rather
+         * than on the effect.
+         */
+        const wire = await this.post("/sso/user", { session_token: sessionToken }, { idempotent: true });
         return {
             user: wire.user,
             subscription: wire.subscription,
@@ -209,8 +216,11 @@ class IdentityResource {
             scope: options.scope,
         });
     }
-    post(path, form) {
+    post(path, form, 
+    /** Only `idempotent` today - for the `/sso/*` reads that are POSTs. */
+    extra) {
         const spec = {
+            ...extra,
             method: "POST",
             path,
             auth: "none",

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

@@ -1,5 +1,5 @@
 "use client";
-import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useState } from "react";
 import { Button, Modal } from "@heroui/react";
 /**
@@ -16,11 +16,19 @@ import { Button, Modal } from "@heroui/react";
  * rejection is caught here rather than escaping - an error thrown out of an
  * async transition reaches the nearest error boundary and takes the page down.
  *
- * The anatomy is HeroUI's: `Modal.Backdrop` owns the open state,
- * `Modal.Container` the sizing, `Modal.Dialog` the focus trap. The trigger
- * goes inside `Modal.Trigger`, which *is* a React Aria button - so pass a
- * plain element, never a `<Button>`, or the nested button swallows the press
- * and the dialog silently never opens.
+ * The anatomy is HeroUI's: the `Modal` root owns the open state,
+ * `Modal.Container` the sizing, `Modal.Dialog` the focus trap. **The trigger
+ * is a direct child of the root**, never wrapped in `Modal.Trigger`.
+ *
+ * That wrapping is what this component used to do, and it meant the dialog
+ * never opened for any caller passing a `<Button>` - which was all of them.
+ * `Modal.Trigger` renders a `div role="button"` inside React Aria's
+ * `Pressable` and relies on a plain `onClick` bubbling up to it; a React Aria
+ * button nested inside calls `e.stopPropagation()` in its own `usePress`
+ * click handler, so the click never arrives. Nothing failed loudly - the
+ * press was simply eaten. The root is `DialogTrigger`, whose `PressResponder`
+ * the trigger registers with directly, so there is no nesting and no
+ * propagation to lose.
  */
 export function ConnectConfirmDialog({ trigger, title, description, confirmLabel = "Confirm", cancelLabel = "Cancel", tone = "danger", onConfirm, }) {
     const [isOpen, setIsOpen] = useState(false);
@@ -33,5 +41,5 @@ export function ConnectConfirmDialog({ trigger, title, description, confirmLabel
             // caller, which owns the toast and the rollback.
         });
     };
-    return (_jsxs(_Fragment, { children: [_jsx(Modal.Trigger, { onClick: () => setIsOpen(true), children: trigger }), _jsx(Modal.Backdrop, { isOpen: isOpen, onOpenChange: setIsOpen, children: _jsx(Modal.Container, { size: "sm", children: _jsxs(Modal.Dialog, { children: [_jsx(Modal.CloseTrigger, { onPress: () => setIsOpen(false) }), _jsx(Modal.Header, { children: _jsx(Modal.Heading, { children: title }) }), description && (_jsx(Modal.Body, { children: _jsx("p", { className: "text-sm text-muted", children: description }) })), _jsxs(Modal.Footer, { children: [_jsx(Button, { variant: "secondary", onPress: () => setIsOpen(false), children: cancelLabel }), _jsx(Button, { variant: tone === "danger" ? "danger" : "primary", onPress: confirm, children: confirmLabel })] })] }) }) })] }));
+    return (_jsxs(Modal, { isOpen: isOpen, onOpenChange: setIsOpen, children: [trigger, _jsx(Modal.Backdrop, { children: _jsx(Modal.Container, { size: "sm", children: _jsxs(Modal.Dialog, { children: [_jsx(Modal.CloseTrigger, { onPress: () => setIsOpen(false) }), _jsx(Modal.Header, { children: _jsx(Modal.Heading, { children: title }) }), description && (_jsx(Modal.Body, { children: _jsx("p", { className: "text-sm text-muted", children: description }) })), _jsxs(Modal.Footer, { children: [_jsx(Button, { variant: "secondary", onPress: () => setIsOpen(false), children: cancelLabel }), _jsx(Button, { variant: tone === "danger" ? "danger" : "primary", onPress: confirm, children: confirmLabel })] })] }) }) })] }));
 }

package/dist/esm/client/provider.js

@@ -133,13 +133,34 @@ export function ConnectProvider({ clientId = "", basePath = "/api/connect", redi
             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, role: null, permissions: [], staff: false, audience: null },
-                error: cause instanceof Error ? cause.message : "Could not reach Connect",
-            });
+            const message = cause instanceof Error ? cause.message : "Could not reach Connect";
+            /*
+             * **A failed read never downgrades a session we already have.**
+             *
+             * This used to replace whatever was known with a signed-out session on
+             * every failure. On a first load that is right - something has to render
+             * rather than skeletons forever - but on a *refresh* it meant one
+             * throttled or dropped request logged the user out of the UI, and the
+             * host app's own guards then acted on that.
+             *
+             * Keeping the last known session is the honest reading: the bridge could
+             * not answer, so what we knew a moment ago is still the best answer we
+             * have. `error` is set either way, so an app that wants to surface
+             * "we've lost touch with Connect" still can.
+             */
+            setResult((previous) => previous?.session.user
+                ? { session: previous.session, error: message }
+                : {
+                    session: {
+                        user: null,
+                        subscription: null,
+                        role: null,
+                        permissions: [],
+                        staff: false,
+                        audience: null,
+                    },
+                    error: message,
+                });
         }
     }, [fetchResource]);
     useEffect(() => {

package/dist/esm/client/use-active-path.js

@@ -17,6 +17,17 @@ let patched = false;
  * actually mounted without an `activePath`. Pass `activePath` (Next:
  * `usePathname()`) and none of this runs at all - which is the recommended
  * path for any app that has a router to ask.
+ *
+ * The notification is deferred to a microtask, and that is load-bearing
+ * rather than tidiness. Next's App Router commits its history entry from
+ * inside a `useInsertionEffect` (`HistoryUpdater` calls
+ * `history.pushState`/`replaceState` there), so a synchronous
+ * `dispatchEvent` reaches `useSyncExternalStore`'s listener *during* that
+ * phase and the re-render it forces is refused: React logs
+ * "useInsertionEffect must not schedule updates" on every navigation. A
+ * microtask runs once the commit's stack has unwound, by which point
+ * `location.pathname` already holds the new value, so the snapshot the store
+ * reads is the same one - only the scheduling moves.
  */
 function patchHistory() {
     if (patched || typeof window === "undefined" || typeof window.history === "undefined")
@@ -26,7 +37,7 @@ function patchHistory() {
         const original = window.history[method];
         window.history[method] = function patchedHistoryMethod(...args) {
             const result = original.apply(this, args);
-            window.dispatchEvent(new Event(LOCATION_CHANGE));
+            queueMicrotask(() => window.dispatchEvent(new Event(LOCATION_CHANGE)));
             return result;
         };
     }

package/dist/esm/next/index.js

@@ -1,6 +1,7 @@
 import { cache } from "react";
 import { ConnectClient } from "../server/client.js";
 import { createConnectHandler } from "../server/handler.js";
+import { ConnectError } from "../errors.js";
 /**
  * Plug-and-play wiring for Next.js.
  *
@@ -211,7 +212,34 @@ async function readSession(request, options) {
     try {
         return await (options.client ?? connectClient()).identity.getUser(token);
     }
-    catch {
+    catch (cause) {
+        /*
+         * `null` means **not signed in**, and nothing else.
+         *
+         * This used to be a bare `catch { return null }`, so every failure - a
+         * throttled read, a five-hundred, a network blip - was reported to the
+         * caller as "there is no session here". That is the worst possible lie for
+         * this particular function, because `requireConnectSession` and every
+         * app guard built on it answer "not signed in" by redirecting to sign-in.
+         *
+         * The result was a login loop nobody could escape: a 429 on the session
+         * read bounced a signed-in user to `/signin`, the OAuth round trip spent
+         * *more* calls against the same exhausted bucket, and the app 429'd again
+         * on the way back. It could only clear when the rate-limit window rolled.
+         * Both of the screenshots that reported this show exactly that sequence.
+         *
+         * So only a genuine session failure answers `null`. `isSessionExpired`
+         * covers the whole family the API deliberately collapses into
+         * `invalid_token` - unknown, expired, revoked, or issued to another
+         * application - which are the cases where signing in again is the correct
+         * and only response.
+         *
+         * Everything else throws. A page that cannot reach Connect gets an error
+         * boundary, which is recoverable and truthful; being quietly signed out is
+         * neither.
+         */
+        if (cause instanceof ConnectError && !cause.isSessionExpired)
+            throw cause;
         return null;
     }
 }
@@ -254,8 +282,18 @@ const cachedAmbientSession = cache(async () => {
  * any other request-scoped read - a page that awaits it above every boundary
  * gives up its static shell.
  *
- * Returns `null` for every failure - an expired session and a missing one both
- * mean "not signed in", and a page guard should not need a try/catch.
+ * Returns `null` when there is **no session** - no cookie, or one Connect
+ * reports as expired, revoked or issued to another application. A page guard
+ * needs no try/catch for those, which are the cases where sending someone
+ * back through sign-in is the right answer.
+ *
+ * **It throws on anything else**, and that is deliberate. It previously
+ * swallowed every failure into `null`, so a rate-limited or unreachable
+ * Connect read as "signed out" - and `requireConnectSession` then redirected a
+ * signed-in user to sign-in, whose OAuth round trip spent more of the same
+ * exhausted budget and 429'd again on return. A login loop that could only end
+ * when the rate-limit window rolled. An error boundary is the honest outcome
+ * for "could not ask", and unlike a spurious sign-out it is recoverable.
  *
  * **Memoized per request for the plain, zero-argument call** - the shape
  * every page, layout and Server Action actually uses - via React's `cache()`.

package/dist/esm/server/client.js

@@ -157,4 +157,4 @@ export class ConnectClient {
     }
 }
 /** Kept in step with `package.json` by `sdk.test.ts`. */
-export const SDK_VERSION = "0.24.0";
+export const SDK_VERSION = "0.25.0";

package/dist/esm/server/http.js

@@ -118,7 +118,9 @@ export async function request(options, spec) {
     // `PUT` and `DELETE` are idempotent by definition - replaying one lands the
     // same end state - so they retry like `GET`. `POST` still needs an
     // `Idempotency-Key` to earn it, because a replayed create is a second row.
-    const idempotent = spec.method !== "POST" || headers["idempotency-key"] !== undefined;
+    const idempotent = spec.idempotent === true ||
+        spec.method !== "POST" ||
+        headers["idempotency-key"] !== undefined;
     const attempts = idempotent ? options.maxRetries + 1 : 1;
     let lastError;
     for (let attempt = 0; attempt < attempts; attempt++) {

package/dist/esm/server/resources/identity.js

@@ -174,7 +174,14 @@ export class IdentityResource {
      * `authorizeUrl()`.
      */
     async getUser(sessionToken) {
-        const wire = await this.post("/sso/user", { session_token: sessionToken });
+        /*
+         * `idempotent` because it is: this asks who a session token belongs to and
+         * writes nothing. Without it a 429 here reached the caller on the first
+         * attempt, and the transport's `Retry-After` backoff - which exists
+         * exactly for this - never ran, because the rule keyed on the verb rather
+         * than on the effect.
+         */
+        const wire = await this.post("/sso/user", { session_token: sessionToken }, { idempotent: true });
         return {
             user: wire.user,
             subscription: wire.subscription,
@@ -204,8 +211,11 @@ export class IdentityResource {
             scope: options.scope,
         });
     }
-    post(path, form) {
+    post(path, form, 
+    /** Only `idempotent` today - for the `/sso/*` reads that are POSTs. */
+    extra) {
         const spec = {
+            ...extra,
             method: "POST",
             path,
             auth: "none",

package/dist/types/client/components/confirm-dialog.d.ts

@@ -1,6 +1,13 @@
 import { type ReactNode } from "react";
 export interface ConnectConfirmDialogProps {
-    /** The control that opens it. Rendered inside `Modal.Trigger`. */
+    /**
+     * The control that opens it, and it **must be a pressable** - a HeroUI
+     * `Button`, or anything else built on React Aria's `useButton`. It is
+     * rendered as a direct child of the `Modal` root, which is React Aria's
+     * `DialogTrigger`: that puts a `PressResponder` around its children and the
+     * trigger registers with it. A plain `<span>` never registers, and React
+     * Aria warns that the responder has no pressable child.
+     */
     trigger: ReactNode;
     title: ReactNode;
     /** What will happen, in the user's words. Name the thing being acted on. */
@@ -25,10 +32,18 @@ export interface ConnectConfirmDialogProps {
  * rejection is caught here rather than escaping - an error thrown out of an
  * async transition reaches the nearest error boundary and takes the page down.
  *
- * The anatomy is HeroUI's: `Modal.Backdrop` owns the open state,
- * `Modal.Container` the sizing, `Modal.Dialog` the focus trap. The trigger
- * goes inside `Modal.Trigger`, which *is* a React Aria button - so pass a
- * plain element, never a `<Button>`, or the nested button swallows the press
- * and the dialog silently never opens.
+ * The anatomy is HeroUI's: the `Modal` root owns the open state,
+ * `Modal.Container` the sizing, `Modal.Dialog` the focus trap. **The trigger
+ * is a direct child of the root**, never wrapped in `Modal.Trigger`.
+ *
+ * That wrapping is what this component used to do, and it meant the dialog
+ * never opened for any caller passing a `<Button>` - which was all of them.
+ * `Modal.Trigger` renders a `div role="button"` inside React Aria's
+ * `Pressable` and relies on a plain `onClick` bubbling up to it; a React Aria
+ * button nested inside calls `e.stopPropagation()` in its own `usePress`
+ * click handler, so the click never arrives. Nothing failed loudly - the
+ * press was simply eaten. The root is `DialogTrigger`, whose `PressResponder`
+ * the trigger registers with directly, so there is no nesting and no
+ * propagation to lose.
  */
 export declare function ConnectConfirmDialog({ trigger, title, description, confirmLabel, cancelLabel, tone, onConfirm, }: Readonly<ConnectConfirmDialogProps>): import("react").JSX.Element;

package/dist/types/next/index.d.ts

@@ -93,8 +93,18 @@ export { handle as GET, handle as POST };
  * any other request-scoped read - a page that awaits it above every boundary
  * gives up its static shell.
  *
- * Returns `null` for every failure - an expired session and a missing one both
- * mean "not signed in", and a page guard should not need a try/catch.
+ * Returns `null` when there is **no session** - no cookie, or one Connect
+ * reports as expired, revoked or issued to another application. A page guard
+ * needs no try/catch for those, which are the cases where sending someone
+ * back through sign-in is the right answer.
+ *
+ * **It throws on anything else**, and that is deliberate. It previously
+ * swallowed every failure into `null`, so a rate-limited or unreachable
+ * Connect read as "signed out" - and `requireConnectSession` then redirected a
+ * signed-in user to sign-in, whose OAuth round trip spent more of the same
+ * exhausted budget and 429'd again on return. A login loop that could only end
+ * when the rate-limit window rolled. An error boundary is the honest outcome
+ * for "could not ask", and unlike a spurious sign-out it is recoverable.
  *
  * **Memoized per request for the plain, zero-argument call** - the shape
  * every page, layout and Server Action actually uses - via React's `cache()`.

package/dist/types/server/client.d.ts

@@ -123,4 +123,4 @@ export declare class ConnectClient {
     constructor(options: ConnectClientOptions);
 }
 /** Kept in step with `package.json` by `sdk.test.ts`. */
-export declare const SDK_VERSION = "0.24.0";
+export declare const SDK_VERSION = "0.25.0";

package/dist/types/server/http.d.ts

@@ -25,6 +25,28 @@ export interface RequestSpec {
      */
     raw?: boolean;
     signal?: AbortSignal;
+    /**
+     * Force this request into the retry path even though it is a `POST`.
+     *
+     * The default rule below - retry anything that is not a `POST`, plus a
+     * `POST` carrying an `Idempotency-Key` - is right about writes and wrong
+     * about the handful of endpoints that are reads wearing a `POST` because
+     * their input is a credential that must not sit in a URL. `POST /sso/user`
+     * is the one that matters: it takes a session token and answers who that
+     * is, replaying it changes nothing, and it is the **most-called endpoint on
+     * the platform** because the SDK asks it on every request a partner serves.
+     *
+     * It was therefore also the only one that could never retry a 429 - the
+     * transport had a correct `Retry-After` backoff that this endpoint was
+     * excluded from by the shape of its verb. A throttled read went straight
+     * back to the caller as a failure, and both session helpers turned that
+     * into "signed out".
+     *
+     * Set it **only** where replaying genuinely cannot change server state.
+     * `POST /sso/token` must never set it: it consumes a one-time authorization
+     * code, and a replay is a second exchange of a code that no longer exists.
+     */
+    idempotent?: boolean;
 }
 export interface TransportOptions {
     baseUrl: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmoops/connect-sdk",
-  "version": "0.24.0",
+  "version": "0.25.0",
   "description": "Official server-side SDK for the CosmoOps Connect platform API - Login with Connect, entitlements, billing and metering.",
   "license": "SEE LICENSE IN LICENSE",
   "type": "commonjs",